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or retailer assumes the entire cost of all necessary servicing or 
repair. 

Valpar International shall have no liability or responsibility 
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respect to any liability, loss, or damage caused directly or 
indirectly by computer programs sold by Valpar International. 

This disclaimer includes but is not limited to any interruption 
of service, loss of business or anticipatory profits or conse¬ 
quential damages resulting from the use or operation of such 
computer programs. 

Defective media (diskettes) will be replaced if diskette(s) 
is returned to Valpar International within 30 days of date of sale 
to user. 

Defective media (diskettes) which is returned after the 30 day 
sale date will be replaced upon the receipt by Valpar of a $12.00 
Replacement Fee. 
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STROLLING THROUGH valFORTH 1.1 


Welcome. For this excursion you'll need an ATARI 800 (or 400) with at least 
24K, a disk drive, monitor, a printer, and valFORTH 1.1. You could even do 

W 1 ?rn^,, the P nnter * Please get everything up and running, and boot 
vait-URTH. 

(To boot the disk, turn the drive(s) on and the computer off. Insert the disk 
in drive 1 and turn the computer on. The disk should now be booting, and the 
monitor speaker should be going beep-beep-beep-beep as valFORTH loads.) 

ERRORS, RECOVERIES, CRASHES 

Before we get started, let's mention the inevitable: Most of the time when 
you make an error you'll receive one of the fairly lucid fig-Forth error 
messages. If you just get a number, this will probably refer to the Atari 
error message list which you can find in the documentation that came with your 
computer. Since the Atari is a rather complex beast, you may sometimes get 
into a tangle that looks worse than it is. Keep your head. If you have party- 
color trash on the screen, for instance, and yet you can still hear the 
"peek-peek-peek" of the key when you hit return, you may have merely blown 
the display list without hurting your system. Try Shift-Clear followed by 
0 GR. . Very often you're home again. If this doesn't work, try a warm start: 
Hold down a CONSOLE button, say START, and while you've got it down, press 
SYSTEM RESET and hold both for a moment until the "valFORTH" title comes up. 

(If you were to push the SYSTEM RESET button alone, you'd get a cold start, 
which takes you back to just the protected dictionary.) A warm start gets 
you back to the "ok" prompt without forgetting your dictionary additions. 

If warm start doesn't work, your system is being kept alive only by those 
wires connected to it; it no longer has a life of its own. The standard 
procedure now is to push SYSTEM RESET alone a few times (cold start) in a 
superstitious manner, and then reboot the system. 

Look carefully at the code that blew the system last time. If you're really 
having trouble debugging, sprinkle a bunch of WAIT's and/or .S's (Stack 
Printouts) through the code, and go through again. The best thing about those 
first few long debugging sessions in any computer language is that they teach 
you the value of writing code carefully. 
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FORMATTING AND COPYING DISKS 


You may have noticed that your system came up in a green screen. In a little 
while you'll be able to change it to anything you like. We'll get to that in 
a moment, but right now type 170 LIST (and then hit RETURN.) Behold the table 
of contents. Our first priority should be to make a working disk by copying 
the original. 

Let's assume that you have a blank, unformatted disk on which to make your 
copy. Notice the line called FORMATTER on screen 170. At the right side of 
this line is probably 92 LOAD, though the number may be different in later 
releases. Type 92 LOAD (or whatever the number is) and wait until the machine 
comes back with "ok". Now you're going to type FORMAT, but for safety's 
sake why not remove the valFORTH disk and insert the blank disk? One never 
knows if newly purchased software will give you warnings before taking action. 
("Warnings" or "Prompts" make a system more friendly.) Ok, now type FORMAT. 

For the drive number you probably want to hit "1", unless you've got more 
than one drive and don't want to' format on the lowest. In answer to the next 
prompt, hit RETURN unless you've changed your mind. Now wait while the machine 
does the job. If you get back "Format OK" you're in business. (If "Format 
Error" comes back, suspect a bad blank disk or drive.) You might as well 
format another disk at this time on which to store your programs. 

Now to make the copy. Return the valFORTH disk to the drive and do 170 LIST 
again. Find DISK COPIERS and do 72 LOAD, or whatever number is indicated. 

When the "ok" prompt comes back, two different disk copying routines are 
loaded: DISKC0PY1 for single drive systems and DISKC0PY2 for multiple 
drive systems. Type whichever of these words is appropriate and follow the 
instructions, ("source" means the disk you want to copy, "dest." is the 

blank "destination" disk.) There are 720 sectors that have to be copied. 

Since this can't be done in one pass, if you are using DISKC0PY1 you will 
have to swap the disks back and forth until you're done. (The computer will 
tell you when.) The less memory you have, the more passes; there is great 
benefit in having 48K. If you have more than one drive, it still takes 
several internal passes, but there is no swapping required. Either way, the 
process takes several minutes with standard Atari disk drives. 



Nice going. Now store the original disk in some safe place. Don't write 
protect your copy yet. First we'll adjust the screen color to your taste. 

Just to see if you really have a good copy, boot it. This can be done'by 
the usual on-off method, or by typing BOOT. 

COLORS 

Before playing with the colors, let's look at something else. Type YLIST, 
and watch the words go by. These are all of the commands that are currently 
in the "dictionary" in memory in your system. You can cause this listing, or 
any other, to pause by hitting CTRL and 1 at the same time. This is a handy 
feature of the Atari. The listing is restarted with the next CTRL 1. 
Additionally, in valFORTH most listings may be aborted by pressing any of the 
three yellow buttons START, SELECT, and OPTION. These three buttons together 
will be referred to as the CONSOLE. 

Do VLIST again, and abort it with a CONSOLE press after a few lines. At the 
top of the list you should see the word TASK. Remember that for a moment. 

Do 170 LIST again. Look over the list and find COLOR COMMANDS, and LOAD as 
appropriate. Now do VLIST again, and stop the list when it takes up about 
half of the screen. Above TASK you now can see a number of new commands, or 
words" as they are commonly called in Forth. These were added to the 
dictionary by the LOAD command. Here's what some of these words do: 

Type BLUE 12 B00TC0L0R, and you get a new display color. Try BLUE 2 B00TC0L0R. 
If you try this action with the number as 4, the letters will disappear, and 
youj 1 have to type carefully to get them back. The number is the luminance 
or lum" and is an even number in the range 0 to 14. The color-name is called 
the "hue." The word "color" will be used to refer to a particular combination 
of hue and lum; hence PINK 6 is a color, PINK is a hue. There are 16 hues 
available and you can read their names from the display, starting with LTORNG 
("light orange") and ending with GREY. (The hues may not match their names on 
your monitor. Later on you'll be able to change the names to your liking, or 
eliminate them altogether to save memory, and just use numbers. For instance, 
PINK is equal to 4.) 

f 

Try out different colors using B00TC0LQR, until you find one you can live with 
for a while. We usually use GREEN 10 or GREEN 12 in-house at Valpar. While 
you are doing this you 1 11 probably make at least one mistake, and the machine 
wiH/eply with an error message like "stack empty." Just hit return to get 
the "ok" back and start whatever you were doing again. Actually, you don't 
even have to get the "ok" back, but it's reassuring to see it there. When 
you ve got a color you like, do VLIST again. Note the first word above TASK. 

-1 should be GREY. Carefully type FORGET GREY, and do VLIST again. Notice 
that GRtY and all words above it are indeed forgotten. That's just what we 
want. Now type SAVE. You'll get a (Y/N) prompt back to give you a chance to 
change your mind, since SAVE involves a significant amount of writing to 
drive #1. _ For practice, check to see that you still have the copy in drive 
one, and if it is there, hit Y, and off we go. When "ok" comes back, remove 
the disk and apply a write protect tab to it. Boot this disk again to see 
that it will come up in your selected color. 
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DEBUGGING 

Look at 170 again. Load the DEBUGGING AIDS, and type ON STACK. You'll see that 
the stack is empty. Great, what's a stack? The best answer to this is to 
suggest that you read Leo Brodie's book. Starting FORTH . This amusing and 
thorough treatment of FORTH starts from the novice level and continues on to 
most of the advanced concepts in FORTH. Starting FORT H is available from many 
sources, including Valpar International. Included with your valFORTH package 
is a document called "Notes on Starting FORTH for the fig-FORTH User" which 
pinpoints differences between Brodie's dialect of FORTH, called 79 Standard, 
and the somewhat more common fig-FORTH on which valFORTH was based. 

It is not feasible to present a course on FORTH in these pages, since FORTH 
is far more powerful than BASIC, which itself requires a fair amount of space 
to present.- However, we'll try to be as considerate as possible to the FORTH- 
innocent. 

The visible stack is a very good debugging and practice tool. Type 
a few integers, say 5 324 -19 0 and hit RETURN. The numbers are now 
visible on thb stack. Top of stack, TOS, is at right. Print the top entry 
by typing " . " and then do DUP. Note that there are now two -19's on top. 

Do " * " to multiply £hem together. Now do DROP to discard the product, 361, 
currently at TOS. Ok, now do SWAP to exchange the 324 and 5 and then do " / " 
to divide 324 by 5. This should leave 64, since the answer is truncated. Now 
type 1000 * and notice that instead of getting 64000 you get -1536. This 
is of course two's complement on a two-byte number. Type U.S which will 
switch the visible stack to unsigned representation. Type .S to go back. 

The words .S and U.S may be used with the visible stack on or off to show 
the stack one time. Now type OFF STACK. Type in a few more numbers, say 
1234567. ON STACK again, and observe that the entries are retained. 

Do OVER to bring a copy of the 6 over the 7. Now DROP it. Do ROT to rotate 
the third from top, 5, to the top. Now do <RQT to put it back. In addition 
to all of these normal routines, valFORTH supports PICK and ROLL both coded 
in 6502 for speed. Notice that the 5th on stack is a 3. 5 PICK will bring a 
copy of it to TOS. Do this and then DROP the 3. Do 5 ROLL to pull the 3 
out of the stack and place it at TOS. DO SP! to clear the s-tack. 




1-4 



One point about number bases: Riqht now you're in DECIMAL. By typinq 
HEX you go into hexadecimal, and typing DECIMAL or its abbreviation DCX 
you get back. And, as usual, virtually any base may be used by typina N BASE 1 
where N is the base you want. Thus, 2 BASE ! gives binary, etc. Some errors, 
particularly during loading, may leave you in an unexpected base, like base 0, 
for instance. If you find the machine acting normally except for numbers, this 
may have happened. A simple DCX will get you back to decimal. The word B? 
will print the current base in decimal. Put 30 on the stack and then do HEX. 

Now do B?. Do DCX to return to decimal. 

While we're on the subject of numbers, do ON and note that it is just a CONSTANT 
equal to 1. Similarly, do OFF and see that it is zero. Try 0 STACK and then 
1 STACK. The words ON and OFF are provided to enhance readability of code, 
but could be substituted by 1 and 0 if desired. The two representations are 
equally fast. 

We mention to the newcomer to FORTH that the stack takes the place of dummy 
variables or dummy parameters in other languages. This reduces memory overhead 
in several ways but does exact a penalty of reduced readability of FORTH source 
code. Consistent and sensible source code formatting can significantly enhance 
readability. The source code on the present disk may be used as a reasonably 
good example of well-arranged code. 



Now a few words about DECOMP. Clear the stack. Type in 3 and 4. Do 
OVER OVER foliowed by 2DUP and notice that these two phrases have the same 
effect. Clear the stack and then turn it off if you like, and do DECOMP 2DUP. 
What you see is a decompilation of 2DUP which indicates that it is indeed 
defined as OVER OVER. Decomp OVER, The word "primitive" in the decompilation 
of OVER indicates that OVER is defined in machine code. 

Decomp LITERAL. The word (IMMEDIATE) after LITERAL in the decompilation 
indicates that LITERAL is immediate. Not all words can be decompiled by 
DECOMP, and sometimes trash will be printed with long pauses between lines. 

In this case, hold down any CONSOLE button (the three yellow ones, remember) 
until the "ok" comes back. This may take several seconds, but rarely much 
longer. 
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PRINTING 


If you have a printer attached, we can generate some hardcopy. Look at screen 
170 again. You can see the line labeled PRINTER UTILITIES. Don't load it, 
though. The printer utilities were loaded automatically when you loaded the 
debugging aids, and so are in the dictionary already. (There is no need to 
have them in twice, though it wouldn't hurt.) You have access to the words P:, 
S:, LISTS, PLISTS, PLIST, and a couple of others relating to output. Do VLIST 
and seeif you can spot this group. As a matter of fact, do ON P: VLIST OFF 
P: all in one shot. ON P: is used to route output to the printer or not. 

OFF P: stops sending to the printer. Try ON P: OFF S: 170 LIST CR OFF P: ON S: 
and notice that this time text is not sent to the display screen, only to the 
printer. That's because of OFF S: . 

Look at screen 170 again, either on display or in hardcopy, and note which 
screen the printer utilities start. Type this number in, but don't type load. 
Instead, after the number, type 10 PLISTS. This prints 10 screens starting 
from the first screen you just typed in. If you have a reasonably smart 
printer, it will automatically paginate, so that the screens are printed 
three to a page. If the printer acts peculiarly after printing each third 
screen, the pagination code in the word EJECT is probably not right for your 
printer. You'll be able to change this later on. 

Now type 30 150 LISTS and after a few blank screens you'll see the entire disk 
go by, except for the boot code. You can pause any time by CTRL 1 or stop 
by holding a CONSOLE button. 

Finally, do ON P: 30 179 INDEX OFF P: to print a disk index. The index is 
made up of the first line of each screen. 


EDITING 

Two editors have been included in this package. The fig (Forth Interest Group) 
Editor and the valFORTH 1.0 Editor. The latter, while a perfectly useable 
video-display editor in its own right, is actually a stripped-down version of 
the valFORTH 1.1 Editor, available with the Utilities/Editor package from Valpar 
International. The 1.0 Editor is provided to give the user some idea of what 
the very powerful 1.1 Editor is like, without actually providing it. (Among 
other things, the 1..1 Editor has a user-definable line buffer of up to 320 lines 
with a 5 line visible window at the bottom of the display. This window can be 
seen at the bottom of the 1.0 Editor, but is inactive.) 
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ihe fig Editor is a general-purpose FORTH line editor, and was the FORTH editing 
workhorse until good video-displays were developed. 

The fig Editor User Manual is located just after this section. It is based 
on that by Bill Stoddart of FIG, United Kingdom, published in the fig-Forth 
installation manual 10/80, and is provided.through the courtesy of the FORTH 
INTEREST GROUP, P.0. Box 1105, San Carlos, CA 94070. Serious Forth programmers 
should write FIG to request their catalog sheet of references and publications. 

Let s look at the valFORTH editor 1.0. Refer to the directory again, screen 170, 
and load the valFORTH editor. (Don't load the fig Editor by mistake.) Before 
proceeding, make sure that the write-protect tab on your disk is secure. The 
word to enter the editor at the screen on top of stack is V. You can remember 
it by thinking of it as "view.' 1 Type 170 V. Screen 170 is now on the display 
again, but in the valFORTH 1.0 Editor rather than as a listing. This Editor 
is a subset of the valFORTH 1.1 Editor available in the Editor/Utilities package, 
which is MUCH more powerful and convenient, and is priced far lower than any 
comparable product of which we are aware. The Editor Command card provided 
shows all of the commands available with the 1.1 Editor. Commands available 
with the 1.0 Editor are marked with asterisks (*) on the card. Let's run 
through them: 

The cursor can be moved as in the Atari "MEMO PAD" mode. That is, hold down 
the control key (CTRL) and rove the cursor around the display with the four 
arrow keys. To enter text (replace mode only in 1.0), position the cursor and 
type it in. Delete characters with the backspace key as usual. The cursor 
will wrap to the next line at the end of a line, and to the top of the screen 
when it goes oft the bottom. You can type at will on this screen since we 
won't save the changes to disk. 

Do a Shift-Insert and notice that a blank line is inserted at the cursor line. 

The bottom line is lost, though it is recoverable in the 1.1 version. Now do 
Shift Delete to remove a line. (Delete is on the Backspace key). These are 
all of the Editing commands available in the 1.0 Editor. There are two methods 
of exiting the editor, CTRL S and CTRL Q. CTRL S marks the screen for saving 
to disk, and CTRL 0 forgets the latest set of editing changes. As usual, 
changes are.not saved immediately. This is accomplished with the word FLUSH 
or by bringing other screens into the buffers and pushing the edited ones out. 
Again, as usual, the EMPTY-BUFFERS command, or its valFORTH abbreviation, MTB, 
will clear all buffers, thus forgetting any changes that have not yet been 
written to disk. 

Fry CTRL Q to exit now. Reedit the screen by typing L. L does not require an 
argument on stack and wili bring the last-editing screen into the editor. The 
words CLEAR and COPY have their normal meanings, as does WHERE, which has had 
the standard fig bug fixed. See the glossary for details. Note that since 
COPY in valFORTH does not FLUSH its changes, careful use allows transfers 
of single screens between disks by swapping disks after COPY and before 
FLUSH. This is particularly handy, for example, for transferring error 
message screens 176-179 between disks. 
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You can make this transfer by doing 


176 176 COPY 177 177 COPY 178 178 COPY 179 179 COPY 

and then swapping in the destination disk and typing FLUSH. You may want 
to define a word to do this automatically: 

: ERRXFR ( — ) 

CR Insert source and press START" WAIT 

180 176 
DO I I COPY 
LOOP 

CR Insert dest. and press START" WAIT 
FLUSH ; 

Because there are four 512 character screen buffers in memory in valFORTH, 
four 512 characters screens at a time is the maximum for this method. 

Bulk screen moves on a single disk or between disks are available with 
the Utilities/Editor Package. 


Note: The word "screen" in Forth refers to an area of the disk. When you 

do 170 LIST you are listing screen 170. In valFORTH there are 180 screens, 

numbered 0-179, on the disk in drive 1. In multiple-drive systems screen 

numbers continue across drives, so that screens 180-349 are on drive 2. 

180 LIST will automatically read from drive 2. For technical reasons screen 0 
should not be used for program code. 

Whichever editor you use for the moment, you can write your programs to a 
blank disk and load them from there. Remember that in fig-FORTH (and so 
also in valFORTH), if you wish to continue loading from one screen to the 
next, all but the last screen should end in -->. You'll see this all through 
the valFORTH 1.1 code. You'll also see ==>. For present purposes you can 
use --> everywhere, and forget about ==>. =:;: > is actually a "smart" version 

of --> that does nothing if the system uses 1024 character screens instead of 
512. r 

If you are a FQRTHER, and wish to use 1024 byte screens, do FULLK. To return 
to 512 character screens, do HALFK. (A working disk may be SAVE'd in either 
condition.) Note that the valFORTH 1.0 Editor will not edit 1024 character 
screens, though the 1.1 version will, and includes special IK notation. In 
the same vein, the word KLOAD -that appears in the source code is a smart load. 
See the Glossary for details. 

To terminate loading one simply omits the --> on the last screen. ;S may be 
used to end loading at any point. Also note that valFORTH —> and ==> are 
smart in the sense that if you wish to stop loading before the machine is 
ready to stop, simply hold down a CONSOLE button. When --> or ==> execute, 
they first check the CONSOLE. If a button is pressed, they stop loading 
instead of continuing with the next screen. 
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Before leaving editing practice, type MTB to empty the disk buffers and assure 
yourself that nothing will be flushed to disk accidentally as you read in new 
screens. Or else, do FLUSH if you really want to save your changes. 

(Remember to remove the write-protect tab if you do.) 


GRAPHICS 



On to Graphics. Check screen 170 and load the Color Commands again, and then 
the Graphics Package. VLIST to see what you've got, and print the list if 
you like. You may notice that GR. is not among these freshly loaded words: 

It is in the kernel, that is, the booted code. Try the following sequence: 

2 GR. (BASIC Graphics mode 2) 

5 5 POS. (Move the graphics cursor) 

G" TEST" (Send text to graphics area) 

1 COLOR (Pick a new graphics color) 

G" TEST" (More text) 

: SMPL 4 0 DO I COLOR G" TEST" LOOP ; (automate) 

SMPL SMPL SMPL (Try it out! 

: MANY BEGIN SMPL ’TERMINAL UNTIL ; (More automation) 

1 GR. (Go somewhere else) 

MANY (Press CONSOLE button to exit) 

17 GR. MANY (Ts*y it in full screen) 

2 GR. 2 PINK 8 SE. MANY (Use SE, to chance rotor 2) 

4 GOLD 8 SE. (Use SE. to change background color). 

0 GR. (Go back to normal text screen.) 


You can also see a quick demons 
listed on screen 170. If ft ! s 
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SOUNDS 

As a final stop on this tour, load the SOUNDS words. The word SOUND acts 
similarly to the Basic command SOUND. In valFORTH it also has the abbrevia¬ 
tion SO. and expects stack arguments like so: 

channel(0-3) frequency#{0-255) distortion(0-14 evens) volume (0-15). 

(We use "CatFish Don't Vote" as a mnemonic). 

Try, for instance 0 200 12 8 SO. and then turn it off with 0 XSND which 
just shuts off the indicated voice, 0, or XSND4 which quiets everything. 

More about sound generation by the Atari may be found in the "sound" section. 

Logical Line Input 

One of the nice features of the Atari OS is that it lets you back the cursor 
over code that you've typed in already, even edit it with various inserts, 
deletes, and retypes, and then hit return to have it reinterpreted. This 
function is supported by valFORTH, and you can re-input up to two full lines 
of text, (and a wee bit more) at a time just by moving the cursor onto the 
''logical line" you wish to re-read. Try it. 

THE GREAT SCREEN SIZE DEBATE 

f 

The "standard" Forth screen is composed of 1024 bytes. This is a nice round 
number, and on a good text display one can have room for that many characters 
plus a few more. However, beyond tradition, there is very little functional 
reason to have 1024 byte screens over several other power-of-2 sizes. In the 
case of Atari and Apple machines, 512 byte screens make video display editors 
much easier to work with, since'one can get a whole screen in the display 
at once. valFORTH supports both 1024 and 512 byte screen modes, but in-house 
at.Valpar we strongly prefer 512 byte screens and recommend that you adopt 
this as your personal standard. If at any time you wish to change to IK to 
help compile software written on IK screens, you can do so with one word, 
FULLK. 
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SAVING YOUR FAVORITE SYSTEM(S) 


Well, you've seen many of the bells and whistles of valFORTH, When you are 
using the language for software development you will probably have a favorite 
set of capabilities that you always want aboard. Rather than loading them 
from scratch each time, why not SAVE them to a formatted disk? Just get 
everything you want into the dictionary. After it's all loaded, put a 
formatted disk into drive 1 and type SAVE. Answer the prompt by pressing "Y" 
unless you have changed your mind, and the computer will save a bootable copy 
of your system dictionary on the blank disk. 

DISTRIBUTING YOUR.PROGRAMS 

If you have a program you wish to distribute, there are two ways in which to 
proceed: 

(1) Make a PROTECTED auto-booting copy of your software by using the 

word AUTO as detailed in the "compiling Auto-Booting Software" section 
of this manual. 

(2) Make a TARGET-COMPILED version of your software, using the valFORTH 
Target Compiler, scheduled for release approximately 9/82. Target 
Compilers allow production of much smaller final FORTH products by 
allowing elimination of unnecessary code, e.g., headers, compiler, 
buffers, etc. 

In addition to the above procedures, Valpar International also 
requires that the message: 

Created in whole or part using valFORTH products of 
Valpar International, Tucson, AZ 85713, USA 
Based on fig-FORTH, provided through the courtesy of 
Forth Interest Group, P.0. Bex 1105, San Carlos, CA 94070 

Hope you’ve enjoyed the tour. Bye now. 
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THE FORTH INTEREST GROUP LINE EDITOR 


FIG EDITOR USER MANUAL 

Based on the Manual 
by Bill Stoddart 
of FIG, United Kingdom 


valFORTH organizes its mass storage into "screens' 1 of 512 characters, with the 
option of 1024. If, for example, a diskette of 90K byte capacity is used 
entirely for storing text, it will appear to the user as 180 screens numbered 
0 to 179. Screen 0 should not be used for program code. Each screen is 
organized as 16 lines with 32 characters per line. 


Selecting a Screen and Input of Text 

To start an editing session the user types EDITOR to invoke the appropriate 
vocabulary. 

The screen to be edited is then selected, using either: 

n LIST ( list screen n and select it for editing ) OR 
n CLEAR ( clear screen n and select for editing ) 

To input new text to screen n after LIST or CLEAR the P (put) command is used. 

Example: 

0 P THIS IS HOW 

1 P TO INPUT TEXT 

2 P TO LINES 0, 1, AND 2 OF THE SELECTED SCREEN. 


Based on material provided through the courtesy of the FORTH INTEREST GROUP, 
P.0. Box 1105, San Carlos, CA 94070. 



Line Editing 


During this description of the editor, reference is made to PAD. This is a 
text buffer which may hold a line of text used by or saved with a line editing 
command, or a text string to be found or deleted by a string editing command. 

PAD can be used to transfer a line from one screen to another, as well as to 
perform edit operations within a single screen. 


Line Editor Commands 

n H Hold line n at PAD (used by system more often than by user}. 

N D Delete line n but hold it in PAD. Line 15 becomes blank as lines 

n+1 to 15 move up 1 line. 

n T Type line n and save it fn PAD. 

n R Replace line n with the text in PAD. 

n I Insert the text from PAD at line n, moving the old line n 
and following lines down. Line 15 is lost. 

n E Erase line n with blanks. 

n S Spread at line n. n and subsequent lines move down 1 line. 

Line n becomes blank. Line 15 is lost. 
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Cursor Control and String Editing 


The screen of text being edited resides in a buffer area of storage. The 
editing cursor is a variable holding an offset into this buffer area. Commands 
are provided for the user to position the cursor, either directly or by search¬ 
ing for a string of buffer text, and to insert or delete text at the cursor 
position. 


Commands to Position the Cursor 


TOP Position the cursor at the start of the screen. 

N M Move the cursor by a signed amount n and print the cursor line. 

The position of the cursor on its line is shown by a • (solid circle). 


String Editing Commands 

F text Search forward from the current cursor position until string 
"text" is found. The cursor is left at the end of the text 
string, and the cursor line is printed. If the string is.not 
found an error message is given and the cursor is repositioned 
at the top of screen. 

B Used after F to back up the cursor by the length of the most 

recent text. 


N Find the next occurrence of the string found by an F command. 

X text Find and delete the string "text." 


C text Copy in text to the cursor line at the cursor position. 

TILL text Delete on the cursor line from the cursor till the end of the 
text string "text." 

NOTE: Typing C with no text will copy a null (represented by a heart) 

into the text at the cursor position. This will abruptly stop 
later compiling! To delete this error type TOP X 'return*. 


S creen Editing Commands 
n LIST List screen n and select it for editing 
n CLEAR Clear screen n with blanks and select it for editing 


nl n2 COPY Copy screen nl to screen n2. 

L List the current screen. The cursor line is relisted after 

the screen listing, to show the cursor position. 

FLUSH Used at the end of an editing session to ensure that all entries 

and updates of text have been transferred to disc. 



Cursor Control and String Editin g 

The screen of text being edited resides in a buffer area of storage. The 
editing cursor is a variable holding an offset into this buffer area. Commands 
are provided for the user to position the cursor, either directly or by search¬ 
ing for a string of buffer text, and to insert or delete text at the cursor 
position. 


Commands to Position the Cursor 

TOP Position the cursor at the start of the screen. 

N M Move the cursor by a signed amount n and print the cursor line. 

The position of the cursor on its line is shown by a • (solid circle). 


String Editing Commands 

F text Search forward from the current cursor position until string 
"text" is found. The cursor is left at the end of the text 
string, and the cursor line is printed. If the string is not 
found an error message is given and the cursor is repositioned 
at the top of screen. 

B Used after F to back up the cursor by the length of the most 

recent text. 


N Find the next occurrence of the string found by an F command. 

X text Find and delete the string "text." 

C text Copy in text to the cursor line at the cursor position. 

TILL text Delete on the cursor line from the cursor till the end of the 

text string "text." 


NOTE: Typing C with no text will copy a null (represented by a heart) 

into the text at the cursor position. This will abruptly stop 
later compiling! To delete this error type TOP X 'return*. 


S creen Editing Commands 
n LIST List screen n and select it for editing 
n CLEAR Clear screen n with blanks and select it for editing 
nl n2 COPY Copy screen nl to screen n2. 

L List the current screen. The cursor line is relisted after 

the screen listing, to show the cursor position. 

FLUSH Used at the end of an editing session to ensure that all entries 

and updates of text have been transferred to disc. 
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Editor Glossary 


TEXT c — 

Accept following text to pad. c is text delimiter. 

LINE n — addr 

Leave address of line n of current screen. This address will be in the 
disc buffer area. 

WHERE nl n2 — 

n2 is the block no., nl is offset into block. If an error is found in 
the source when loading from disc, the recovery routine ERROR leaves 
these values on the stack to help the user locate the error. WHERE 
uses these to print the screen and line nos. and a picture of where 
the error occurred. 

R# --- addr 

A user variable which contains the offset of the editing cursor from 
the start of the screen. 

#L0CATE — nl n2 

From the cursor position determine the line-no n2 and the offset into 
the 1ine nl. 

#LEAD — line-address offset-to-cursor 

#LAG — cursor-address count-after-cursor-till-EOL 

-MOVE addr line-no 

'Move a line of text from addr to line of current screen. 

H n — 

Hold numbered line at PAD. 

E n — 

Erase line n with blanks. 

S n — 

Spread. Lines n and following move down, n becomes blank. 

D n 

Delete line n, but hold in pad. 

M n — 

Move cursor by a signed amount and print its line. 

T n — 

Type line n and save in PAD. 

L 

List the current screen. 
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R 


n — 

-n Replace line n with the text in PAD. 

n — 

Put the following text on line n. 

I n — 

Spread at line n and insert text from PAD. 

TOP 

Position editing cursor at top of screen. 

CLEAR n — 

Clear screen n, can be used to select screen n for editing. 

FLUSH 

Write all updated buffers to disc. 

COPY nl n2 — 

Copy screen nl to screen n2. 

-TEXT Addr 1 count Addr 2 -- boolean 

True if strings exactly match. 

MATCH cursor-addr bytes-left-till-EOL str-addr str-count 

— tf cursor-advance-till-end-of-matching-text 

— ff bytes-left-till-EOL 

Match the string at str-addr with all strings on the cursor line 
forward fromthe cursor. The arguments left allow the cursor R# to 
be updated either to the end of the matching text or to the start of the 
next line. 

1LINE — f 

Scan the cursor line for a match to PAD text. Return flag and update 
the cursor R# to the end of matching text, or to the start of the 
next line if no match is found. 

FIND 

Search for a match to the string at PAD, from the cursor position 
till the end of screen. If no match found issue an error message 
and reposition the cursor,at the top of screen. 

DELETE n — 

Delete n characters prior to the cursor. 

N 

Find next occurrence of PAD text, 

F 

Input following text to PAD and search for match from .cursor position 
till end of screen. 
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B 

Backup cursor by text in PAD. 

X 

Delete next occurrence of following text. 

TILL 

Delete on cursor line from cursor to end of the following text. 

C 

Spread at cursor and copy the following text into the cursor line. 
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CREATING DISKS FOR PRODUCTION 


RELOCATING BUFFERS 

The purpose of this section is to show you how to avoid incorporating buffer 
space into an auto-booting program, thereby saving more than 2K in memory 
requirement for the machine on which the program will eventually run. 

Fig-FORTH (and so valFORTH) uses a virtual memory arrangement which allows 
disk areas to be accessed in a manner similar to that used to access semiconductor 
memory. We won't go into detail here; those wishing to find out more about this 
can contact FIG for documentation at: 

FORTH INTEREST GROUP 
P.0. Box 1105 
San Carlos, CA 94070 

or they can puzzle out the process by starting at the word BLOCK. For our present 
purposes, however, we simply note that the virtual memory scheme requires that 
some continuous area of memory be allotted as buffer space for disk operation, 
valFORTH as delivered has buffer space for four 512 byte "screens" at a time. 

Each screen is composed of four blocks of 132 bytes each: 128 bytes of actual 
data, corresponding to a sector, and four bytes of identification and delimiting 
data. This produces a total of 4 x 4 x 132 = 2112 bytes that are needed for 
programming and compilation* but are generally not required when software is 
actually run. In order to get the full use of your computer, particularly for 
the purposes of producing auto-booting software like games, you'll need to know 
how memory is mapped and what changes you can make in the mapping. During the 
following discussion refer to the memory map provided with your documentation. 

You will note from the memory map that the buffers are placed just above the 
kernel (boot-up) valFORTH dictionary. The dictionary pointer is set just past 
the buffers, so new word definitions will be compiled in above the end of the 
buffers. Why such an odd location? Read on... 

* Those used to seeing the buffers at the top of memory will quickly realize 
that this is impractical on the Atari, since that area is used for display 
lists. Although it is possible to an extent to fool the operating system into 
thinking that it has less memory than it actually has, and thus "reserve" an 
area at the top of memory, this is a troublesome proposition. 

* Another approach is to put the buffers just below the kernel dictionary, 
which has been done in at least one FORTH-for-Atari release. While this is 
safe, it sacrifices 2K bytes during run time unless rather clever programming 
techniques are used on each program to put code into the dormant buffer area. 

* Clearly, the buffers should be put somewhere above the dictionary but below 
the display-list area, and a simple means to relocate them should be supported. 
This is precisely what you have in valFORTH. 


* In a pinch, you can compile using only 264 bytes of buffer memory. 



When you have a program that will compile and run, preferably without errors, 

and you'd like to create a smaller auto-booting version, follow this procedure: ^ 

* Boot the valFORTH disk. 

Decide on the area to which to relocate the buffers: If the program can be 
loaded without leaving the 0 Graphics mode or doing anything else to high memory 
while loading, then the result printed by the sequence 

0 GR. DCX 741 @ 2113 - U (See note below.) 

will be a safe place to put the buffers; 741 @ is the Atari OS pointer to just 
below the current display list. (If you will be using Transients, a capability 
of the Utilities/Editor package, their default location is 

DCX 741 @ 4000 - 

so you would be better off to put the buffers at, say, 

DCX 741 @ 6113 - 


to avoid conflict). 

Find the buffer relocation utility listed in the table of contents startinq 
on screen 1.70 of the val FORTH disk, and load it. This is a self-prompting 
utility that directs you to relocate the buffers and then forget the utility, 
toiiow the directions. You'll receive a verification messaqe after the buffers 
have been moved. 


Type 




' TASK DP ! 

to move the dictionary pointer below the old buffer area. (Advanced programmers: 
This is not a typo. The cfa of TASK points to NEXT.) 

* Now load your program as usual. You should probably create an auto-booting 
program at this point, rather than doing anything else, since if you run the 
program now it may write into your relocated buffers and conceivably even attempt 
a write to your disk. So, create an auto-booting version as directed in the 
Auto—booting section above. Remember that if the program is for distribution, 
you MUST protect your software and ours by using the AUTO command. 

*****caution***** 


The buffers start out just above the kernel dictionary, as indicated, and for 
normal programming they should be LEFT THERE: Several routines on the valFORTH 
disk and other disks in this product line use the area between pad and the 
bottom of the display list as a scratch area for extensive disk transfers. 
DISKC0PY1 and DISKC0PY2 on the valFORTH disk are examples. 


Note: The buffers should generally be relocated to an even address because of ^ 

an Atari OS bug. See also Note 1 at end of valFORTH 1.1 Glossary. v_ 
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COMPILING AUTO-BOOTING SOFTWARE 

/our purchase of valFORTH and its associated packages also grants you a single- 
user license for the software. You may not copy valFORTH or its associated 
Valpar International products for any purpose other than for your own use as 
back-up copies. However, a word called AUTO has been provided to allow you 
to create a copy of your software that is suitable for distribution. The word 
AUTO does several things. 


* AUTO provides extensive protection both for your software and the valFORTH 
and auxiliary programs on which it is based. Your product may still be copied 
by normal methods, but the programming concepts on which it is based will be 
very difficult to analyze. The valFORTH and auxiliary programs will be rendered 
useless except to run your program. Since AUTO scrambles all headers in the 
code before saving to disk or cassette, even direct examination of the code on 
the medium is not very revealing. This provides essentially all the protection 
of headerless code. 


* AUTO will create a disk that autoboots to the FORTH word of your choice. 
This usually will be the last word defined in your program. In addition, a 
disk created using AUTO will not have exit points: That is, even if your 
program terminates, or makes an error because of an undiscovered bug, it will 
not exit to valFORTH and the "ok" prompt. Instead, it will automatically 
attempt to start again at the original auto-boot word, and will do so unless 
an error has disabled the system. 


* AUTO allows repetitive saving of your protected software to disk and cassette 
in one sitting, with extensive prompting. This provides a short-run production 
environment. (Remember that if you want to save to cassette, the cassette 
recorder should be attached to the system at boot time; if it is attached 
after booting, the computer may not know that the recorder is there and may 
fail when trying to AUTO to cassette). 


To run AUTO and create your bootable software: 

(1) Load valFORTH. 

(2) Relocate buffers to save 2K+, if desired (see below). 

(3) Load your program. 

(4) DISPOSE transients, if you use them. (The Transient utilities come with 
the Utilities/Editor package, and allow use of "disposable assemblers" 
and the like). 

(5) Find the Auto-Boot Utility section on the valFORTH disk by referring to 
the directory starting on screen 170, and load as indicated. 

(6) Type AUTO cccc where "cccc" is the word which you wish to execute on 
auto-booting the software. You will now be prompted through the rest 
of the procedure. On exiting from AUTO you will fall through to the 
auto-booting program that you have just protected. 


DISTRIBUTING YOUR PROGRAMS 




If you have a program you wish to distribute, there are two ways in which to 
proceed: 

(1) Make a PROTECTED auto-booting copy of your software by using the 

word AUTO as detailed in the "Compiling Auto-Booting Software" section 
of this manual. 

(2) Make a TARGET-COMPILED version of your software, using the valFORTH 
Target Compiler, scheduled for release approximately 9/82. Target 
Compilers allow production of much smaller final FORTH products by 
allowing elimination of unnecessary code, e.g., headers, compiler, 
buffers, etc. 


In addition to the above procedures, Valpar International also 
requires that the message: 

Created in whole or part using valFORTH products of 
Valpar International, Tucson, AZ 85713, USA 
Based on fig-FORTH, provided through the courtesy of 
Forth Interest Group, P.0. Box 1105, San Carlos, CA 94070 

be included either on the outside of the media (diskette, cassette, 
or other) as distributed, or in the documentation provided with the 
product. Please note that failure to include this message with 
products that include valFORTH code may be regarded as a copyright 
violation. 
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valFORTH 1.1 SYSTEM EXTENSIONS 


GRAPHICS, COLORS, AND SOUNDS 


Graphics 

The Graphics package follows the Atari BASIC graphics set as closely as 
possible, and is identical in most respects. As in BASIC, the most complex 
parts of Graphics are DRAWTO (abbreviated "DR.") and FIL, and even these are 
not too obscure. Find the Graphics Demo by looking at the directory start¬ 
ing on screen 170, and load it. Try the word FBOX. Now look at the code 
that produced this effect, if you like. The general explanation is as 
follows: 

Display positions are denoted by two coordinates, a horizontal and a vertical. 
The 0,0 point is in the upper left hand corner, and the vertical coordinate 
increases as you go down the display, while the horizontal coordinate increases 
as you go to the right. This is all familiar from BASIC. 

In graphics modes, a single point at position X Y can be plotted by X Y PLOT. 
The color of the point will be that in the color register declared by the 
last COLOR command. A line, again of the color in the register declared by 
the last color command, may then be drawn to point XI Y1 by XI Y1 DR. . The 
word FIL may be used to fill in an area as described in the Atari manual, 
and as illustrated in the FBOX example. The color register for the fill is 
the one whose number is on the stack when FIL is executed. Essentially, to 
set up FIL you draw in boundaries and pick two points you wish to FIL between. 
The first of these points is set up either by a DR. or PLOT command, or by 
valFORTH’s POSIT command. POSIT has the advantage of not requiring that you 
put anything into the place where you are positioning yourself. The second 
point for the FIL command is then set up by using POS. . The fill is then 
performed by putting a number on stack (the color register for the fill) and 
then doing FIL. 

If you are in a text mode, a single character, c , can be sent to the display 
by ASCII c CPUT. Text strings can be sent to the display with G" cccc " and 
in addition will have the color in the register specified by the last COLOR 
command before the string is output. This is a significant enhancement to 
BASIC. 



Graphics and Color Glossary: 


SETCOLQR nl n2 n3 — 

Color register nl (0...3 and 4 for background) is set to hue n2 (0 to 15) 
and luminance n3 (0-14, evens). 

SE. nl n2 n3 — 

Alias for SETCOLOR. 

GR. n - 

Identical to GR. in BASIC. Adding 16 will suppress split display. 

Adding 32 will suppress display preclear. In addition, this GR. will 
not disturb player/missiles. 

POS. x y — 

Same as BASIC POSITION or POS. Positions the invisible cursor if in 
a split display mode, and the text cursor if in 0 GR. . 

POSIT x y - 

Positions and updates the cursor, similar to PLOT, but without changing 
display data. 

PLOT x y — 

Same as BASIC PLOT. PLOTs point of color in register specified by last 
COLOR command, at point x y. 

DRAWTO x y — 

Same as BASIC DRAWTO. Draws line from last PLOT'ted, DRAWTO'ed or 
POSIT'ed point to x y, using color in register specified by last COLOR 
command. 


DR. x y — 

Alias for DRAWTO. 


FIL b - 

Fills area between last PLOT'ed, DRAWTO'ed or POSIT’ed point to last 
position set by POS., using the color in register b. 


G" — 

Used in the form G" ccocc". Sends text cccc to text area in non-0 
Graphics mode, starting at current cursor position, in color of 
register specified by last COLOR command prior to cccc being output. 

G" may be used within a colon definition, similar to .". 

GTYPE addr count — 

Starting at addr, output count characters to text area in non-0 Graphics 
mode, starting at current cursor position, in color of register speci¬ 
fied by last COLOR command. 

LOC. x y -- b 

Positions the cursor at x y and fetches the data from display at that 
position. Like BASIC LOCATE and LOC. . Note that since the word LOCATE 
has a different meaning in valFORTH (it is part of the advanced editor 
in the Utilities/Editor package), the name is not used in this package. 
(Advanced users: We could put Graphics in its own vocabulary, but this 
would add some inconvenience.) 
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( 0 ") 

Run-time code compiled in by G". 

P0S@ - x y 

Leaves the x and y coordinates of the cursor on the stack. 

CPUT b — 

Outputs the data b to the current cursor position. 

CGET — b 

Fetches the data b from the current cursor position. 

>SCD cl - c2 

Converts cl from ATASCII to its display screen code, c2. 

Example: ASCII A >$CD 88 @ C! 

will put an "A" into the upper left corner of the display. 

SCD> cl -- c2 

Converts cl from display screen code to ATASCII c2. 

See >SCD. 

>BSCD addrl addr2 count -- 

Moves count bytes from addrl to addr2, translating from ATASCII 
to display screen code on the way. 

BSCD> addrl addr2 count -- 

Moves count bytes from addrl to addr2, translating from display 
screen code to ATASCII on the way. 

COLOR b — 

Saves the value b in the variable COLDAT. 

CLRBYT -- addr 

Variable that holds data from last COLOR command. 

GREY — 0 

GOLD - 1 

ORNG -- 2 

RDORNG — 3 

PINK — 4 

LVNDR — 5 

BLPRPL — 6 (CONSTANTS) 

PRPLBL — 7 

BLUE — 8 

LTBLUE - 9 

TURQ — 10 
GRNBL — 11 
GREEN — 12 
YLWGRN — 13 
GRNGRN — 14 
LTORNG — 15 

B00TC0L0R hue lum -- 

Sets up hue for playfield 2 (text background) and lum for playfield 1 
(letter intensity) in 0 Graphics mode. Lum of playfield 2 is set at 4. 
After using B00TC0L0R, doing SAVE will create a system disk with the 
selected color. 
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Sounds 


The actual production of sound by the Atari machines is rather complex and 
the reader is referred to the many recent (first half 1982) articles on this 
subject in various magazines. Here we will restrict cormients to the function 
of the Atari audio control register. This is an eight bit register which 
valFORTH shadows by the variable AUDCTL. The bits have the following 
functions: 

bit 7: Change 17 bit polycounter to 9 bit polycounter. 

Affects distortions 0 and 8. 

bit 6: Clock channel 0 with 1.79 Mhz instead of 64 Khz. 

bit 5: Clock channel 2 with 1.79 Mhz instead of 64 Khz. 

bit 4: Clock channel 1 with channel 0 instead of 64 Khz. 

bit 3: Clock channel 3 with channel 2 instead of 64 Khz. 

bit 2: Use channel 2 as crude high-pass on channel 0. 
bit 1: Use channel 3 as crude high-pass on channel 1. 
bit 0: Change normal 64 Khz to 15 Khz. 

The value n may be sent to the audio control register by doing n FILTER!. 

SOUND chan freq dist vol -- 

Sets up the sound channel "chan" as indicated. 

Channel: 0-3. 

Frequency: 0-255, 0 is highest pitch. 

Distortion: 0-14, evens only. 

Volume: 0-15. 

Suggested mnemonic: CatFish Don't Vote 

SO. chan freq dist vol -- 

Alias of SOUND. 

FILTER! n — 

Stores n in the audio control register and into the valFORTH shadow 
register, AUDCTL. Use AUDCTL when doing bit manipulation, then do 
FILTER!. (FILTER! does a number of housekeeping chores, so use it 
instead of a direct store into the hardware register.) 

AUDCTL - addr 

A variable containing the last value sent to the audio control register 
by FILTER!. Used for bit manipulation since the audio control register 
is write-only. 

XSND n — 

Silences channel n. 

XSND4 

Silences all channels. 




TEXT OUTPUT AND DISK PREPARATION GLOSSARY 


S: flag — 

If flag is true, enables handler that sends text to text screen. If 
false, disables the handler. (See PFLAG in main glossary.) ON S: etc. 

P : flag — 

If flag is true, enables handler that sends text to printer. If false, 
disables the handler. (See PFLAG in main glossary.) OFF P: etc. 

BEEP — 

Makes a raucous noise from the keyboard. Is put in this package for 
lack of a better place. 

ASCII c, -- n (executing) 
c, -- (compiling) 

Converts next character in input stream to ATASCII code. If executing, 
leaves on stack. If compiling, compiles as literal. 


EJECT — 

Causes a form feed on smart printers if the printer handler has been 
enabled by ON P:. May need adjustment for dumb or nonstandard printers. 

LISTS start count — 

From start, lists count screens. May be aborted by CONSOLE button at 
the end of a screen. 

PLIST scr -- 

Lists screen scr to the printer, then restores former printer handler 
status. 

PLISTS start cnt -- 

From start, lists cnt screens to printer three to a page, then restores 
former printer handler status. May be aborted by CONSOLE button at the 
end of a screen. 

FORMAT — 

With prompts, will format a disk in drive of your choice. 

(FMT) nl - n2 

Formats disk in drive nl. Leaves 1 for good format, otherwise error number. 
Note: Because of what‘appears to be an OS peculiarity, this operation must 
not be the first disk access after a boot. 

DISKC0PY1 — 

With prompts, copies a source to a destination disk on single drive, 
with swapping. Smart routine uses all memory from PAD to bottom of 
Display List, producing minimum number of swaps. 

DISKC0PY2 - 

With prompts, copies disk in drive 1 to disk in drive 2 using memory 
like DISKC0PY1. 



DEBUGGING UTILITIES 


DECOMP cccc 

Does a decompilation of the word cccc if it can be found in the active 
vocabularies. 

Although DECOMP is very smart, like most FORTH decompilers it will 
become confused by certain constructs, and will begin to print trash, 
with pauses in between while it looks for more trash to print. When 
this happens, simply hold down a CONSOLE button until DECOMP exits. 
This sometimes takes as much as 10 seconds, depending on luck. 


CDUMP addr n — 

A character dump from addr for at least n characters. (Will always 
do a multiple of 16.) 

#DUMP addr n -- 

A numerical dump in the current base for at least n characters. 

(Will always do a multiple of 8.) 

(FREE) — n 

Leaves number of bytes between bottom of display list and PAD. This is 
essentially the amount of free dictionary space, if additional memory 
is not being used for player/missiles, extra character sets, and so on. 


FREE — 

Does (FREE) and then prints the stack and "bytes". 

H. n -- 

Prints n in HEX, leaves BASE unchanged. 

STACK flag - 

If flag is true, turns on visible stack. If flag is false, turns off 
visible stack. 

• S 

Does a signed, nondestructive stack printout, TOS at right. Also 
sets visible stack to do signed printout. 

U.S ... — ... 

Does unsigned, nondestructive stack printout, TOS at right. Also 
sets visible stack to do unsigned printout. 

B? 

Prints the current base, in decimal. Leaves BASE undisturbed. 

CFALIT cccc, -- cfa (executing) 

cccc, -- (compiling) 

Gets the cfa (code field address) of cccc. If executing, leaves it on 
the stack; if compiling, compiles it as a literal. Not precisely a 
debugging tool, but finds use in DECOMP. 





FLOATING POINT WORDS 


The floating-point package uses the Atari floating point routines in the 
operating system ROM in the same way that Atari Basic does. The routines 
are rather slow, and there are no trigonometric functions internal to the 
Atari. (SIN, COS, TAN, ATN, and ATN2 have been programmed and are available 
in the Advanced Graphics/Floating Point Package.) LOG and EXP are included in the 
operating system ROM and are supported in the present package, in base 10 
and base e. Note that in the directory on screen 170 it is indicated that 
the ASSEMBLER must be loaded before loading the floating-point package. 

Floating point words have a six byte representation in the Atari OS, and since 
the stack has a 60 byte maximum, a maximum of 10 floating point numbers can be 
on the stack at a time. In practice, this maximum often becomes 9 since some 
fp routines use the stack as a scratch area. 

Operations involving floating-point numbers generally leave floating-point 
results. Exceptions are the words FIX, which takes a positive floating 
pointer number less than 32767.5 and leaves a rounded integer; and the 
floating-point comparison operators, F=, F<, etc., which leave flags. To 
get a floating-point number on the stack, use the word FLOATING or its alias, 

FP, followed by a number in Fortran ! 'E" format. For example, 

FP 12345 
FP 12345.6 
FP -12345.8 
FP +5432E-16 
and FP -8E18 

will all leave floating-point numbers on the stack. Floating-point variables 
and constants are also supported. 

It has been our experience that mistakes are common when first using this 
package. One must remember to use F* and not *, F+ and not +, and so on, 
when doing fp operations. Remember also that integers and fp numbers can’t 
be mixed by operations: Either convert the fp number by FIX, or the integer 
by FLOAT, and then use the appropriate operation. 

Create new words as usual. For instance, to define a floating-point square 
root function, write 

: FSQRT ( fp -- fp ) 

LOG FP 2 F/ EXP ; 

Overflow and underflow, and illegal operations such as dividing by 0, taking 
logarithms of negative numbers, or Fixing a negative number cause undefined 
and rather unpredictable results, though they do not harm the system. 

(Additional words in the Utilities/Editor Package cause all but one of these 
operations to give correct or useable results; logarithms of negatives cannot 
be approximated with Real numbers.) 

The maximum and minimum numbers are generous, about 1E97 and IE-97, and it is 
sometimes possible to exceed these limits during computation. Atari's internal 
representation of floating point numbers is awkward. Refer to the Atari OS 
manual, available from Atari, for details if needed. 
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FLOATING-POINT GLOSSARY 


In the following, "fp" is used to indicate a floating-point number (six bytes) 
on the stack. The terms "top-of-stack," "2nd-on-stack" etc., have been used 
with the obvious meanings even though, because fp numbers are six bytes, their 
physical positions on the stack will not match the usual ones. 

FCONSTANT cccc, fp -- 

cccc: --fp 

The character string is assigned the constant value fp. When cccc is executed, 
fp will be put on the stack. 

Example: FP 3.1415926 FCONSTANT PI 

FVARIABLE cccc, fp — 

cccc: addr — 

The character string cccc is assigned the initial value fp. When cccc is 
executed, the addr (two bytes) of the value of cccc will be put on the stack. 
Example: FP 0 FVARIABLE X 

FP 18.4 X F! 

FOUR fpl -- fpl fpl 

Copies the fp number at top-of-stack. 

FDROP fp — 

Discards the fp number at top-of-stack. 

FOVER fp2 fpl — fp2 fpl fp2 

Copies the fp number at 2nd-on-stack to top-of-stack. 

FLOATING cccc, - fp 

Attempts to convert the following string, cccc, to a fp number. Stops on 
reaching first unconvertible character and skips the rest of the string. If 
no characters convertible, leaves unpredictable fp number on stack. 

FP cccc, --fp 

Alias for FLOATING. 

F@ addr — fp 

Fetches the fp number whose address is at top-of-stack. 

F! fp addr -- 

Stores fp into addr. Remember that the operation will take six bytes in 
memory. 

F. fp — 

Type out the fp number at top-of-stack. Ignores the current value in BASE 
and uses base 10. 

F? addr — 

Fetches a fp number from addr and types it out. 



F+ fp2 fpl -- fp3 

Replaces the two top-of-stack fp items, fp2 and fpl, with their fp sum, fp3. 

F- fp2 fpl — fp3 

Replaces the two top-of-stack fp items, fp2 and fpl, with their difference, 
fp3=fp2~fpl. 

F* fp2 fpl — fp3 

Replaces the two top-of-stack fp items, fp2 and fpl, with their product, fp3. 
F/ fp2 fpl -- fp3 

Replaces the two top-of-stack fp items, fp2 and fpl, with their quotient, 
fp3=fp2/fpl. 

FLOAT n -- fp 

Replaces number at top-of-stack with its fp equivalent. 

FIX fp (non-neg, less than 32767.5) — n 

Replaces fp number at top-of-stack, constrained as indicated, with its 

integer equivalent. 

LOG fpl — fp2 

Replaces fpl with its base e logarithm, fp2 0 Not defined for fpl negative. 
L0G10 fpl -- fp2 

Replaces fpl with its base 10 decimal logarithm, fp2. Not defined for fpl 
negative. 

EXP fpl -- fp2 

Replaces fpl with fp2, which equals e to the power fpl. 

EXP10 fpl-~fp2 

Replaces fpl with fp2, which equals 10 to the power fpl. 

F0= fp — flag 

If fp is equal to floating-point 0, a true flag is left. Otherwise, a false 
flag is left. 

F= fp2 fpl -- flag 

If fp2 is equal to fpl, a true flag is left. Otherwise, a false flag is left. 
F> fp2 fpl -- flag 

If fp2 is greater than fpl, a true flag is left. Otherwise, a false flag is 
left. 

F< fp2 fpl -- flag 

If fp2 is less than fpl, a true flag is left. Otherwise, a false flag is left. 
FLITERAL fp — 

If compiling, then compile the fp stack value as a fp literal. This definition 
is immediate so that it will execute during a colon definition. The intended 
use is: 

: xxx [ calculate ] FLITERAL ; 

Compilation is suspended for the compile time calculation of a value. 
Compilation is resumed and FLITERAL compiles the value on stack. 



FLIT — fp 

Within a colon definition, FLIT is automatically compiled before each fp 
number encountered as input text. Later execution by the system of FLIT as 
it is encountered in the dictionary cause the context of the next 6 dictionary 
addresses to be pushed to the stack as a fp number. FLIT is also compiled 
in explicitly by FLITERAL. 


ASCF addr — fp 

An ASCII-to-floating-point conversion routine. Uses Atari OS routine. The 
routine reads string starting at addr and attempts to create a floating point 
number. If string is not a valid ASCII floating-point representation, leaves 
undefined result on stack. Used by FLOATING. 

FS fp - 

System routine. Sends fp argument on stack to Atari register FRO. Experts 
only. 


>F -- fp 

System routine. Fetches fp argument from Atari register FRO. Experts only. 

<F fpl fp2 — 

System routine. Sends fpl and fp2 to Atari registers FR1 and FRO respectively. 
Experts only. 


F.TY 

System routine. Types out last fp number converted by FASC. 

CIX addr — 

System variable. One byte offset pointer in buffer pointed to by INBUF. 
Experts only. 


INBUF addr — 

System variable. Used by ASCF to know where ASCII string to be converted is 
located. 


FR1 - n 

System constant. Atari internal register address. 
FRO -n 

System constant. Atari internal register address. 


FPOLY addr count — 

A system routine for advanced users doing polynomial evaluation. 

The polynomial P(Z) = SUM(i=0 to n) (A(i)*Z**i) is computed by the following 
standard method: 

P(Z) = (...(A(n)*Z + A(n-l))*Z + ... + A(1))*Z + A(0) 

The address addr points to the coefficients A(i) stored sequentially in memory, 
with the highest order coefficient first. The count is the number of coeffi¬ 
cients in the list. The independent variable Z, in floating-point, should be 
sent to FRO using FS. FPOLY is then executed. The result put'on the stack 
using >F. Note that FPOLY is intended to be used in a Forth word. 

Trigonometric functions and general polynomial expansions, for example, may 
be defined more simply with the help of this routine. 
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FLG10 

System routine used by L0G10. 

FLG 

System routine used by LOG. 

FEX 

System routine used by EXP. 

FEX10 

System routine used by EXP10. 

FDIV 

System routine used by F/. 

FMUL 

System routine used by F*. 

FSUB 

System routine used by F-. 

FADD 

System routine used by F+. 

FPI 

System routine used by FIX. 

IFP 

System routine used by FLOAT. 

FASC 

System routine. Does floating-point-to-ASCII conversion on the fp number 
in FRO and leaves string at address pointed to by INBUF. Last byte of string 
has most significant bit set. Used by F.TY. 

AFP 

System routine used by ASCF. 
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OPERATING SYSTEM 


This package implements the computer's Operating System I/O routines. The 
850 (R5-232C) driver package may be loaded into the dictionary by using the 
word RS232, which will then support references to devices "Rl" through "R4." 

The code for this section was originally written by Patrick Mullarky, and 
published through the Atari Program Exchange. It is used here by permission 
of the author. 

OS GLOSSARY 

OPEN addr nl n2 n3 -- n4 

This word opens the device whose name is at addr. The device is opened 
on channel n3 with AUX1 and AUX2 as nl and n2 respectively. The device 
status byte is returned as n4. The name of a device may be produced in 
various ways: For a single character name, say "S" for the screen 
handler, 

ASCII S PAD C! 

will leave the ASCII value of S at PAD. Then 

PAD 803 OPEN 

will open the screen handler on channel 3 with AUX1 = 8 (write only) 
and AUX2 = 0. If you have the UTILITIES/EDITOR Package, longer names 
may be set up simply by using the word " . 

CLOSE n — 

Closes channel n. 

PUT bl n - b2 

Outputs byte bl on channel n, returns status byte b2. 

GET n -- bl b2 

Gets byte bl from channel n, returns status byte b2. 

GETREC addr nl n2 n3 

Inputs record from channel n2 up to length nl. Returns status byte n3. 
PUTREC addr nl n2 - n3 

Outputs nl characters starting at addr through channel n2. Returns 
status byte n3. 

STATUS n - b 

Returns status byte b from channel n. 

DEVSTAT n - bl b2 b3 

From channel nl gets device status bytes bl and b2, and normal status 

byte b3. 

SPECIAL bl b2 b3 b4 b5 b6 b7 b8 — b9 

Implements the Operating System "Special" command. AUX1 through AUX6 
are bl through b6 respectively, command byte is b7, channel number is 
b8. Returns status byte b9. 


RS232 

Loads the Atari 850 drivers into the dictionary (approx 1.8K) through 
a three-step.bootstrap process. Executing this command more than once 
without turning the 850 off and on again will crash the system. 
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valForth Glossary 


Based on the fig-Forth Glossary 
Provided through the courtesy of 
Fourth Interest Group, P.0. Box 1105, San Carlos, CA 94070 


This glossary contains all of the word definitions in Release 1.1 of valForth. 

The definitions are presented in the order of their ASCII sort. 

The first line of each entry shows a symbolic description of the action of 
the procedure on the parameter stack. The symbols indicate the order in whichinput 
parameters have been placed on the stack. Two dashes indicate the execution 
point; any parameters left on the stack are listed. In this notation, the top of 
the stack is to the right. 

The symbols include: 

addr memory address 

b 8 bit byte (i.e. hi 8 bits zero) 

c 7 bit ASCII character (hi 9 bits zero) 

d 32 bit signed double integer, most significant portion with 

sign on top of stack. 

f boolean flag. 0=false, non-zero=true 

tf boolean true flag=non-zero 

ff boolean false f]ag=0 

n 16 bit signed integer number 

u 16 bit unsigned integer 

The capital letters on the right show definition characteristics: 

C May only be used within a colon definition. A digit indi¬ 

cates number of memory addresses used, if other than one. 

E Intended for execution only. 

L0 Level Zero definition of FORTH-78 

LI Level One definition of FORTH-78 

P Has precedence bit set. Will execute even when compiling, (immediate) 

U A user variable. 

V A valForth word not in fig-Forth. 

B A word adopted from Leo Brodie's Starting Forth . 

Unless otherwise noted, all references to numbers are for 16 bit signed integers. 
The high byte of 16 bit numbers is the second byte on the stack, with the sign in the 
leftmost bit. For 32 bit signed double numbers, the most significant part (with the 
sign) is on top. 

All arithmetic is implicitly 16 bit signed integer math, with error and under¬ 
flow indication unspecified. 




LO 




j 

SCSP 


# 




#s 


'( 


( 


) 

)( 



n addr — 

Store 16 bits of n at address. Pronounced "store". 


Save the stack position in CSP. Used as part of the compiler 
security. 

dl - d2 LO 

Generate from a double number dl, the next ASCII character which 
is placed in an output string. Result d2 is the quotient after 
division by BASE, and is maintained for further processing. Used 
between <# and #>. See #S. Pronounced "number". 

d -- addr count LO 

Terminates numeric output conversion by dropping d, leaving the text 
address and character count suitable for TYPE. Pronounced "number- 
bracket". 

dl — d2 LO 

Generates ASCII text in the text output buffer, by the use of #, 
until a zero double number d2 results. Used between <# and #>. 
Pronounced "numbers". 

-- addr P,L0 

Used in the form: 

1 nnnn 

Leaves the parameter field address of dictionary word nnnn. As a 
compiler directive, executes in a colon-definition to compile the 
address as a literal. If the word is not found after a search of 
CONTEXT and CURRENT, an appropriate error message is given. Pro¬ 
nounced "tick". 


V ,E ,P 

Used in the form: 

'( WORDQ W0RD1 . . . WQRDN ) ( W0RDN+1 . . .WORDM ) 
which executes as follows: If WORDO is found in a search of CONTEXT 
and CURRENT, then execute W0RD1 . . . WORDM. Generally used for con¬ 
ditional compilation. Note that if no words are to be included in 
the second group, then )( and ) must be separated by at least TWO 
blanks. 


P ,L0 

Used in the form: 

( cccc) 

Ignore a comment that will be delimited by a right parenthesis on 
the same line. May occur during execution or in a colon-definition. 
A blank after the leading parenthesis is required. 


V,E,P 

No operation. Used in '( constructs. 

V ,E ,P 

Scans text input pointer past ")". Used in '( constructs. 


C+ 

The run-time procedure, compiled by ." which transmits the following 
in-line text to the selected output device. See ." 
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(/LOOP) 

(;CODE) 

(+LOOP) 

(ABORT) 

(DO) 

(FIND) 

(FMT) 

(LINE) 

(LOOP) 

(NUMBER) 

(SAVE) 

* 

*/ 


n — B ,C2 

Execution time code of /LOOP. 

L 

The run-time procedure, compiled by ;C0DE, that rewrites the code 
field of the most recently defined word to point to the following 
machine code sequence. See ;C0DE. 

n — C2 

The run-time procedure compiled by +L00P, which increments the loop 
index by n and tests for loop completion. See +L00P. 


Executes after an error when WARNING is -1. This word normally exe¬ 
cutes ABORT, but may be altered (with care) to a user's alternative 
procedure. 

C 

The run-time procedure'compiled by DO which moves the loop control 
parameters to the return stack. See DO. 

addrl addr2 — pfa b tf (ok) 

addrl addr2 -- ff (bad) 

Searches the dictionary starting at the name field address addr2, 
matching to the text at addrl. Returns parameter field address, 
length byte of name field and boolean true for a good match. If no 
match is found, only a boolean false is left. 

nl — n2 V 

Formats disk in drive nl. Leaves 1 for good format, otherwise error 
number. Note: Because of what appears to be an OS peculiarity, this 
operation must not be the first disk access after a boot. 

nl n2 -- addr count 

Convert the line number nl and the screen n2 to the disc buffer address 
containing the data. 


C2 

The run-time procedure compiled by LOOP which increments the loop 
index and tests for loop completion. See LOOP. 

dl addrl — d2 addr2 

Convert the ASCII text beginning at addrl+1 with regard to BASE. 

The new value is accumulated into double number dl, being left as d2. 
Addr2 is the address of the first unconvertible .digit. Used by NUMBER. 

V 

Used by SAVE, not generally used in programs. Sets up various 
parameters 'preparatory to writing a bootable disk. 

nl n2 -- prod LO 

Leave the signed product of two signed numbers. Pronounced "star". 

nl n2 n3 — n4 LO 

Leave the ratio n4 = nl*n2/n3 where all are signed numbers. Retention 
of an intermediate 31 bit product permits greater accuracy than would 
be available with the sequence: 

nl n2 * n3 / 

Pronounced "star-slash". 



*/MOD 


+ 

+ ! 

+- 

+BUF 


+LOOP 


+ORIGIN 


--> 

-DISK 


nl n2 n3 -- n4 n5 LO 

Leave the quotient n5 and remainder n4 of the operation nl*n2/n3. 

A 31 bit intermediate product is used as for */. Pronounced "star 
slash-mod". 

nl n2 -- sum LO 

Leave the sum nl+n2. 

n addr -- LO 

Add n to the value at the address. Pronounced "plus-store". 

nl n2 -- n3 

Apply the sign of n2 to nl, which is left as n3. 
addl — addr2 f 

Advance the disc buffer address addrl to the address of the next 
buffer addr2. Boolean f is false when addr2 is the buffer presently 
pointed to by variable PREV. 

nl — (run) 

addr n2 — (compile) P,C2,L0 

Used in a colon-definition in the form: 

DO ... nl +L00P 

At run-time, +L00P selectively controls branching back to the corres¬ 
ponding DO based on nl, the loop index and the loop limit. The signed 
increment nl is added to the index and the total compared to the limit. 
The branch back to DO occurs until the new index is equal to or greater 
than the limit (nl>0), or until the new index is equal to or less that 
the limit (nl<0). Upon exiting the loop, the parameters are discarded 
and execution continues ahead. 

At compile time, +LQ0P compiles the run-time word (+L00P) and the branch 
offset computed from HERE to the address left on the stack by DO. 
n2 is used for compile time error checking. 

n -- addr 

Leave the memory address relative by n to the origin parameter area, 
n is the minimum address unit, either byte or word. This definition 
is used to access or modify the boot-up parameters at the origin area. 

n -- LO 

Store n into the next available dictionary memory cell, advancing the 
dictionary pointer; (comma) 

nl n2 -- diff LO 

Leave the difference of nl~n2, 

P,L0 

Continue interpretation with the next disc screen. Pronounced "next- 
screen" . 

addr n2 n3 flag -- n4 V 

Used by R/W. Not generally used in programs. This word performs a 
single-sector read or write on a disk. Addr is the starting RAM 
address, n2 is the sector number (1-720), n3 is the drive number 
(1-4), and the flag is 1 for read and 0 for write. On return, n4 
will be zero if there were no problems, or it will be a DOS error 
number if a DOS error occurred. 



-DUP 

-FIND 

-TRAILING 


.LINE 

.R 

/ 

/LOOP 

/MOD 


nl -- nl (if zero) 

nl — nl nl (non-zero) LO 

Reproduce nl only if it is non-zero. This is usually used to copy a 
value just before IF, to eliminate the need for an ELSE part to drop 
it. 


-- pfa b tf (found) 

ff (not found) 

Accepts the next text word (delimited by blanks) in the input stream 
to HERE, and searches the CONTEXT and then CURRENT vocabularies for 
a matching entry. If found, the dictionary entry's parameter field 
address, its length byte, and a boolean true are left. Otherwise, 
only a boolean false is left. 

addr nl -- addr n2 

Adjusts the character count nl of a te v t string beginning address to 
suppress the output of trailing blanks, i.e. the characters at 
addr+nl to addr+n2 are blanks. 

n — LO 

Print a number from a signed 16 bit two's complement value, converted 
according to the numeric BASE. A trailing blanks follows. Pronounced 
"dot". 

P ,L0 

Used in the form: 
cccc" 

Compiles an in-line string cccc (delimited by the trailing ") with an 
execution procedure to transmit the text to the selected output device. 
If executed outside a definition, ." will immediately print the text 
until the final ", The maximum number of characters may be an installa¬ 
tion dependent value. See (."). 

line scr -- 

Print on the terminal device, a line of text from the disc by its line 
and screen number. Trailing blanks are suppressed. 

nl n2 — 

Print the.number nl right aligned in a field whose width is n2. No 
following blank is printed. 

nl n2 -- quot LO 

Leave the signed quotient of nl/n2. 

n — B ,C2 

Like +L0GP, but uses an unsigned limit, index, and increment. Thus 
loop index may pass $7FFF without mishap. Faster than +L00P and may 
be used instead of +L00P if increment is positive (and index doesn't 
cross $7FFF.) 

nl n2 — rem quot _ LO 

Leave the remainder and signed quotient of nl/n2. The remainder has 
the sign of the dividend. 
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0 12 3 

— n 

These small numbers are used so often that it is attractive to define 
them by name in the dictionary as constants. 

n 

0# 

n — flag 

Leaves a true flag if n is not equal to 0. Otherwise, leaves 
flag. Pronounced "zero not equal". 

V 

a false 


0< 

n — f 

Leave a true flag if the number is less than zero (negative), 
leave a false flag. 

L0 

otherwise 


0= 

n -- f L0 

Leave a true flag if the number is equal to zero, otherwise leave a 
false flag. 


0> 

n -- flag 

Leaves a true flag if n is greater than 0. Otherwise leaves 
flag. 

V 

a false 


OBRANCH 

f - 02 

The run-time procedure to conditionally branch. If f is false (zero), 
the following in-line parameter is added to the interpretive pointer 
to branch ahead or back. Compiled by IF, UNTIL, and WHILE. 


1+ 

nl — n2 

Increment nl by 1. 

LI 


1- 

nl — n2 

Subtract one from nl. Pronounced "one-minus". 

B 


2* 

nl — n2 

Multiply nl by two. Pronounced "two-star" or "two-times". 

B 


2+ 

nl -- n2 

Leave nl incremented by 2. 



2- 

nl -- n2 

Leave nl decremented by 2. 



2/ 

nl — n2 

Divide nl by two. Pronounced "two-slash". 

B 


2DR0P 

d — 

Drops the double number at T0S. 

B 


2DUP 

d -- d d 

Copies double number at T0S. 

B 


20VER 

d2 dl — d2 dl d2 

Copies double number at 20S to T0S. 

B 


2 ROT 

d3 d2 dl — d2 dl d3 ' V 

Moves double number at 30S over two double numbers on 20S and T0S. 

r " 

2 SWAP 

d2 dl — dl d2 

Exchanges double numbers at T0S and 20S. 

B 
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P,E,LO 

Used in the form called a colon-definition: 

: cccc ; —^ 

Creates a dictionary entry defining cccc as equivalent to the follow¬ 
ing sequence of Forth word definitions until the next or 

';CQDE ! . The compiling process is done by the text interpreter as long 
as STATE is non-zero. Other details are that the CONTEXT vocabulary 
is set to the CURRENT vocabulary and that words with the precedence 
bit set (P) are executed rather than being compiled. 


; ~ P,C,L0 

Terminate a colon-definition and stop further compilation. Compiles 
the run-time ;S. 

;C0DE — P,C,L0 

Used in the form: 

: cccc .... ;C0DE assembly mnemonics 

Stop compilation and terminate a new defining word cccc by compiling 
(;C0DE). Set the CONTEXT vocabulary to Assember, assembling to machine 
code the following mnemonics. 

When cccc later executes in the form: 
cccc nnnn 

the word nnnn will be created with its execution procedure given by 
the machine code following cccc. That is, when nnnn is executed, it 
does so by jumping to the code after nnnn. An existing defining word 
must exist in cccc prior to ;C0DE. 

;S -- P ,lo 

Stop interpretation of a screen. ;S is also the run-time word com¬ 
piled at the end of a colon-definition which returns execution to the 
calling procedure. 

< nl n2 — f LO 

Leave a true flag if nl is less than n2; otherwise leave a false 
flag. 

<# - LO 

Set-up for pictured numeric output formatting using the words: 

<# # #S SIGN #> 

The conversion is done on a double number producing text at PAD. 
Pronounced "Bracket Number". 


<= n2 nl -- flag V 

Leaves true flag if n2 is less than or equal to nl. Otherwise, leaves 
false flag. 

<> n2 nl -- flag V 

Leaves true flag if n2 and nl are unequal. Otherwise, leaves false 
flag. 
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<BUILDS 


C ,L0 


Used within a colon-definition: 

: cccc <BUILDS ... 

D0ES> ... ; 

Each time cccc is executed, <BUILDS defines a new word with a high- 
level execution procedure. Executing cccc in the form: 
cccc nnnn 

uses <BUILDS to create a dictionary entry for nnnn with a call to the 
D0ES> part for nnnn. When nnnn is later executed, it has the address 
of its parameter area on the stack and executes the words after D0ES> 
in cccc. <BUILDS and D0£S> allow run-time procedures to be written 
in high-level rather than in assembler code (as required by -.CODE). 

nl n2 — f LO 

Leave a true flag if nl=n2; otherwise leave a false flag. 


If using 512 byte (half-K) screen, does --> otherwise, no 
action is taken. Used to chain screens in half-K format 
that will still load correctly in valFORTH full-K format. 


> 


>= 

>R 


? 


? 1K 

?C0MP 

?CSP 

TERROR 

?EXEC 

? EX IT 


nl n2 — f LO 

Leave a true flag if nl is greater than n2; otherwise a false flag. 

n2 nl — flag V 

Leaves true flag if n2 is greater than or equal to nl. Otherwise, 
leaves false flag. 

n — C ,L0 

Remove a number from the computation stack and place as the most access 
able on the return stack. Use should be balanced with R> in the same 
definition. 

addr -- LO 

Print the value contained at the address in free format according to 
the current base. 

-- flag V 

Leaves a true flag if C/L is 64, indicating IK screens. Otherwise, 
leaves a false flag. 


Issue error message if not compiling. 

Issue error message if stack position differs from value saved in CSP. 
f n — 

Issue an error message number n, if the boolean flag is true. 


Issue an error message if not executing. 


V,C 

Caution: Use only within a DO LOOP. Within DO LOOP, will cause exit 
at end of current loop if a CONSOLE button is depressed when 7EXIT is 
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7LQADING 

?PAIRS 

?STACK 

7TERMINAL 

@ 

@EX 

ABORT 

ABS 

ACCEPT 

AGAIN 


executed. Will work only in the word in which the DO LOOP is defined, 
not in a word nested further down. 


Issue an error message if not loading, 
nl n2 -- 

Issue an error message if nl does not equal n2. The message indicates 
that compiled conditionals do not match. 

Issue an error message if the stack is out of bounds. This definition 
may be installation dependent. 

— b 

Perform a test of the terminal keyboard for actuation of a CONSOLE 
key. Leaves 0 if none actuated, leaves 1 for START, 2 for SELECT, 

4 for OPTION, and sums for combinations. 

addr -- n LO 

Leave the 16 bit contents of address. 

addr — V 

Fetches the word (presumably a code field address) at addr, and 
then causes it to execute. Used for conditional execution without 
the speed and memory loss of flags and/or case statements. Typical 
use would be AUXOP @EX where the variable AUXOP had been loaded with 
the cfa of the desired word, by ' DESIREDWORD CFA AUXOP ! . Pro¬ 

nounced n fetch-ex." 


L.0 

Clear the stacks and enter the execution state. Return control to 
the operators terminal, printing a message appropriate to the instal¬ 
lation. 

n — u 

Leave the absolute value of n as u. 


addr count -- 

Same as EXPECT, except that ACCEPT uses the O.S. line input 
routine which allows full MEMO PAD editing functions to be 
utilized. EXPECT prevents hazards such as Shift-Clear while 
ACCEPT does not. SEE EXPECT. 


addr n — (compiling) 

Used in a colon-definition in the form: 

BEGIN ... AGAIN 

At-run-time, AGAIN forces execution to return to corresponding BEGIN. 
There is no effect on the stack. Execution cannot leave this loop 
(unless R> DROP is executed one level below). 

At compile time, AGAIN compiles BRANCH with an offset from HERE to 
addr. n is used for compile-time error checking. 


P,C2 ,L0 


ALLOT 


n -- 

Add the signed number to the dictionary pointer DP 
reserve dictionary space or re-origin memory. 


LO 

May be used to 


AND 

B/BUF 

B/SCR 

BACK 

BASE 

BEGIN 


BL 

BLANKS 

BLK 

BLOCK 


nl n2 — n3 |n 

Leave the bitwise logical and of nl and n2 as n 3 . 

— n 

This constant leaves the number of bytes per disc buffer the bvte 
count read from disc by BLOCK. tne Dyte 

-- n 

This constant leaves the number of blocks per editing screen, 
addr -- 

Calculate the backward branch offset from HERE to addr and compile 
into the next available dictionary memory address. P 

— addr .. 

A user variable containing the current number base used for input and 

output conversion. put and 


P,L0 


—_ addr n (compiling) 

Occurs in a colon-definition in form* 

BEGIN ... UNTIL 
BEGIN ... AGAIN 
BEGIN ... WHILE ... REPEAT 

At run-time, BEGIN marks the start of a sequence that may be repetitively 

fretSrn'to BEGlS V wilfnr ^REPEAT. When executing UNTIL 

ACA?n IL ° CCU J lf the top of the stack ^ false; for 

AGAIN and REPEAT a return to BEGIN always occurs. 

error^checking 6 ' BEGIN 1eaV6S 1t$ return address and " for compiler 


A constant that leaves the ASCII value for "blank 11 
addr count — 

Fill an area of memory beginning at addr with blanks. 

addr U ^g 

A user variable containing the block number being interpreted, "if 
zero, input is being taken from the terminal input buffer. 

n -- addr ,0 

Leave the memory address of the block buffer containing block n If 
the block is not already in memory, it is transferred from disc to 

b f fe K WaS 1eaSt recently wr1tten - If the block occupying 
that buffer has been marked as up-dated, it is rewritten to disc before 
block n is read into the buffer. See also BUFFER, R/W UPDATE FLUSH 
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BOOT 

V 

Boots disk in drive 1. Same effect as turning computer on and off. 

BRANCH 

C2 ,L0 

The run-time procedure to unconditionally branch. An in-line offset 
is added to the interpretive pointer IP to branch ahead or back. 

BRANCH is compiled by'ELSE, AGAIN, REPEAT. 

BUFFER 

n -- addr 

Obtain the next memory buffer, assigning it to block n. If the con¬ 
tents of the buffer is marked as updated, it is written to the disc. 

The block is not read from the disc. The address left is the first 
byte within the buffer for data storage. 

C! 

b addr -- 

Store 8 bits at address. 

c, 

b — 

Store 8 bits of b into the next available dictionary byte, advancing 
the dictionary pointer.' 

C/L 

- n V 

A CONSTANT equal to the number of characters per line in the ValForth 
screen. Usually 32, but may be 64 if 1024 byte screens in use. 

C? 

addr — V 

Fetches a byte from addr and prints it using . . 

C@ 

addr — b 

Leave the 8 bit contents of memory address. 

CFA 

pfa — cfa 

Convert the parameter field address of a definition to its code 
field address. 

CMOVE 

from to count — 

Move the specified quantity of bytes beginning at address from to address 
to. The contents of address from is moved first proceeding toward 
high memory. 

COLD 

The cold start procedure to adjust the dictionary pointer to the minimum 
standard and restart via ABORT. May be called from the terminal to 
remove application programs and restart. 

COMPILE 

C2 

When the word containing COMPILE executes, the execution address of 
the word following COMPILE is copied (compiled) into the dictionary. 

This allows specific compilation situations to be handled in addition 
to simply compiling an execution address (which the interpreter al¬ 
ready does). 

CONSTANT 

n — LO 

A defining word used in the form: 
n CONSTANT cccc 

to create word cccc, with its parameter field containing n. When 
cccc is later executed, it will push the value of n to the stack. 
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CONTEXT 


- addr u,LO 

A user variable containing a pointer to the vocabulary within which 
dictionary searches will first begin. 

COUNT addrl — addr2 n l_o 

Leave the byte address addr2 and byte count n of a message text begin¬ 
ning at address addrl. It is presumed that the first byte at addrl 
contains the text byte count and the actual text starts with the second 
byte. Typically, COUNT is followed by TYPE. 

CR — LO 

Transmit a carriage return and line feed to the selected output device. 

CREATE 

A defining word used in the form: 

CREATE cccc 

by such words as CODE and CONSTANT to create a dictionary header for 
a FORTH definition. The code field contains the address of the word's 
parameter field. The new word is created in the CURRENT vocabulary. 

CSAVE - v 

Creates a bootable copy of RAM-resident system up to HERE on cassette. 
Computer beeps twice to indicate user must press Record and Play but¬ 
tons on recorder, prior to pressing RETURN. CSAVE expects leaderless 
tape. If your tape has a leader, wind to just before the end of leader, 


CSP 

CURRENT 


D! 

D+ 

D+- 

D. 



-- addr y 

A user variable temporarily storing the stack pointer position, for 
compilation error checking. 

-- addr 

Address of a pointer to second word in the parameter field of the current 
vocabulary. (The current vocabulary is the one to which new definitions 
are added.) 

d addr — y 

Stores double number d into addr. 

dl d2 — dsum 

Leave the double number sum of two double numbers, 
dl n — d2 

Apply the sign of n to the double number dl, leaving it as d2. 


Print a signed double number from a 32 bit two's complement value. 
The high-order 16 bits are most accessable on the stack. Conversion 
is performed according to the current BASE. A blank follows. Pro¬ 
nounced "D-dot." 

d n — 

Print a signed double number d right aligned in a field n characters 
wide. 

addr — d y 

Fetches double number d from addr. 
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DABS 


d — ud 

Leave the absolute value ud of a double number. 


DECIMAL — LO 

Set the numeric conversion BASE for decimal input-output. 


DEFINITIONS ~ LI 

Used in the form: 

cccc DEFINITIONS 

Set the CURRENT vocabulary to the CONTEXT vocabulary. In the example, 
executing vocabulary name cccc made it the CONTEXT vocabulary and exe¬ 
cuting DEFINITIONS made both specify vocabulary cccc. 

DIGIT c nl — n2 tf (ok) 

c nl -- ff (bad) 

Converts the ASCII character c (using base nl) to its binary equiva¬ 
lent n2, accompanied by a true flag. If the conversion is invalid, 
leaves only a false flag. 

DLITERAL d -- d (executing) 

d -- (compiling) P 

If compiling, compile a stack double number into a literal. Later 
execution of the definition containing the literal will push it to 
the stack. If executing, the number will remain on the stack. 


DMINUS 

DO 


DQES> 


DP 


dl - d2 

Convert dl to its double number two's complement, 
nl n2 -- (execute) 

addr n -- (compile) P,C2;L0 

Occurs in a colon-definition in form: 

DO ... LOOP 
DO .. +L00P 

At run-time, DO begins a sequence with repetitive execution controlled 
by a loop limit nl and an index with initial value n2. DO removes 
these from the stack. Upon reaching LOOP, the index is incremented by 
one. Until the new index equals or exceeds the limit, execution loops 
back to just after DO; otherwise, the loop parameters are discarded and 
execution continues ahead. Both nl and n2 are determined at run-time 
and may be the result of other operations. Within a loop "I" will copy 
the current value of the index to the stack. See I, LOOP, +L00P, 
LEAVE. 

When compiling within the colon-definition, DO compiles (DO), leaves the 
following address addr and n for later error checking. 


LO 

A word which defines the run-time action within a high-level defining 
word. D0ES> alters the code field and first parameter of the new word 
to execute the sequence of compiled work addresses following D0ES>. 
Used in combination with <BUILDS, When the D0ES> p'art executes it 
begins with the address of the first parameter of the new word on the 
stack. This allows interpretation using this area or its contents. 
Typical uses include the Forth assembler, multi-dimensional arrays, 
and compiler generation. 

— addr U,L 

A user variable, the dictionary pointer, which contains the address of 
the next free memory above the dictionary. The value may be read by 
HERE and altered by ALLOT, or directly. 
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DPL 


DRO 

DR1 


DROP 

DUP 

ELSE 


EMIT 


" addr u,LO 

A user variable containing the number of digits to the right of the 
decimal on double integer input. It may also be used hold output column 
location of a decimal point, in user generated formatting. The default 
value on single number input is -1. 


Installation dependent commands to select disc drives, by presetting 
OFFSET. The contents of OFFSET is added to the block number in BLOCK 
to allow for this selection. Offset is supressed for error text so 
that it may always originate from drive 0. 

n — LO 

Drop the number from the stack. 

n -- n n LO 

Duplicate the value on the stack. 

addrl nl — addr2 n2 (compiling) 

P,C2 ,L0 

Occurs within a colon-definition in the form: 

IF ... ELSE ... ENDIF 

At run-time, ELSE executes after the true part following IF. ELSE 
forces execution to skip over the following false part and resumes 
execution after the ENDIF. It has no stack effect. 

At compile-time, ELSE emplaces BRANCH reserving a branch offset, leaves 
the address addr2 and n2 for error testing. ELSE also resolves the 
pending forward branch from IF by calculating the offset from addrl 
to HERE and storing at addrl. 

c — LO 

Transmit ASCII character c to the selected output device. OUT is 
incremented for each character output. 


EMPTY-BUFFERS LO 

Mark all block-buffers as empty, not necessarily affecting the contents. 
Up-dated blocks are not written to the disc. This is also an initiali¬ 
zation procedure before first use of the disc. Alias is MTB. 

ENCLOSE addrl c — addrl nl n2 n3 

The text scanning primitive used by WORD. From the text address 
addrl and an ASCII delimiting character c, is determined the byte 
offset to the first non-delimiter character nl, the offset to the first 
delimiter after the text n2, and the offset to the first character 
not included. This procedure will not process past an ASCII "null", 
treating it as an unconditional delimiter. 

END P,C2 ,L0 

This is an "alias" or duplicate definition for UNTIL. 
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ENDIF 


ERASE 

ERROR 


EXECUTE 

EXPECT 

FENCE 

FILL 

FIRST 

FLD 

FORGET 


addr n — (compile) P,CO,LO 

Occurs in a colon-definition in form: 

IF ... ENDIF 

IF ... ELSE ... ENDIF 

At run-time, ENDIF serves only as the destination of a forward branch 
from IF or ELSE. It marks the conclusion of the conditional structure. 
THEN is another name for ENDIF. Both names are supported in fig-FORTH. 
See also, IF and ELSE. 

At compile-time, ENDIF computes the forward branch offset from addr to 
HERE and stores it at addr. n is used for error tests. 

addr n -- 

Clear a region of memory to zero from addr over n addresses, 
n — in blk 

Execute error notification and restart of system. WARNING is first 
examined. If 1, the text of line n, relative to screen 176 of drive 0 
is printed. This line'number may be positive or negative, and beyond 
just screen 176. If WARNING=0, n is just printed as a message number 
(non disc installation). If WARNING is -1, the definition (ABORT) 
is executed, which executes the system ABORT. The user may cautiously 
modify this execution by altering (ABORT). fig-FORTH saves the contents 
of IN and BLK to assist in determining the location of the error. Final 
action is execution of QUIT. 

addr -- 

Execute the definition whose code field address is on the stack. The 
code field address is also called the compilation address. 

addr count — LQ 

Transfer characters from the terminal to address, until a "return" or 
the count of characters have been received. One or more nulls are 
added at the end of the text. 

-- addr U 

A user variable containing an address below which FORGETting is trapped. 
To forget below this point, the user must alter the contents of FENCE. 

addr quan b -- 

Fill memory at the address with the specified quantity of bytes b. 

— addr 

A constant that leaves the address of the first (lowest) block buffer. 

— addr U 

A user variable for control of number output field width. Presently 
unused in fig-FORTH. 


E,L0 

Executed in the form: 

FORGET cccc 

Delete definition named cccc from the dictionary with all entries 
ohvsicallv following it. 
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FORTH — p,Ll 

The name of the primary vocabulary. Execution makes FORTH the CONTEXT 
vocabulary. Until additional user vocabularies are defined, new user 
definitions become a part of FORTH. FORTH is immediate, so it will 
execute during the creation of a colon-definition, to select this voca¬ 
bulary at compile time. 

FULLK — V 

Sets C/L to 64 and B/SCR to 8, producing 1024 byte screen operation. 

May be SAVEd in this condition. (See HALFK) 

GFLAG -- addr V 

A variable that holds a Graphics mode cursor control flag. When the 
value at GFLAG is non-zero, valForth assumes a split-screen is opera¬ 
tive, and will use the alternate cursor-address variables provided by 
the Operating System to use the text window at the bottom of the display. 

HALFK — V 

Sets C/L to 32 and B/SCR to 4, producing 512 byte screen operation. May 
be SAVEd in this condition. (See FULLK) 

HERE -- addr LO 

Leave the address of the next available dictionary location. 

HEX - LO 

Set the numeric conversion base to sixteen (hexadecimal). 

HLD — addr LO 

A user variable that holds the address of the latest character of 
text during numeric output conversion. 

HOLD c — LO 

Used between <# and #> to insert an ASCII character into a pictured 
numeric output string, 
e.g. 2E HOLD will place a decimal point. 

I — n C ,L0 

Used within a DO-LOOP to copy the loop index to the stack. Other 
use is implementation dependent. See R. 

I' - n B 

Copies the second item on the return stack to the stack. Generally 
used to get the index of the present DO LOOP after an item has been 
pushed to the return stack for convenience. 

ID. addr -- 

Print a definition's name from its name field address. 


V-15 



IMMEDIATE 

IN 

INDEX 

INTERPRET 

J 

KEY 

KLOAD 


f — (run-time) 

addr n (compile) P,C2,LO 

Occurs in a colon-definition in form: 

IF (tp) ... ENDIF 

IF (tp) ... ELSE (fp) ... ENDIF 

At run-time, IF selects execution based on a boolean flag. If f is 
true (non-zero), execution continues ahead thru the true part. If f is 
false (zero), execution skips till just after ELSE to execute the false 
part. After either part, execution resumes after ENDIF. ELSE and its 
false part are optional.; if missing, false execution skips to just 
after ENDIF. 

At compile-time IF compiles OBRANCH and reserves space for an offset 

at addr. addr and n are used later for resolution of the offset and 

error testing. 


Mark the most resent!y made definition so that when encountered at 
compile time, it will be executed rather than being compiled, i.e. 
the precedence bit in its header is set. This method allows defini¬ 
tions to handle unusual compiling situations, rather than build them 
into the fundamental compiler. The user may force compilation of an 
immediate definition by preceeding it with {COMPILE] . 

— addr l_o 

A user variable containing the byte offset within the current input 
text buffer (terminal or disc) from which the next text will be ac¬ 
cepted. WORD uses and moves the value of IN. 

from to -- 

Print the first line of each screen over the range from, to. This is 
used to view the comment (first) lines of an area of text on disc screens 


The outer text interpreter which sequentially executes or compiles 
text from the input stream (terminal or disc) depending on STATE. If 
the word name cannot be found after a search of CONTEXT and then CURRENT 
it is converted to a number according to the current base. That also 
failing, an error message echoing the name with a " ?" will be given. 
Text input will be taken according to the convention for WORD. If a 
decimal point is found as part of a number, a double number value will 
be left. The decimal point has no other purpose than to force this 
action. See NUMBER. 

n B 

Copies the third item on the return stack to the stack. Generally 
used to get the index of the next outer DO LOOP. 


- c LO 

Leave the ASCII value of the next terminal key struck. 

screen -- V 

If C/L has a value other than 64, then the number on stack is doubled. 

In either case, LOAD is then executed. The purpose is to allow smart 
conditional loading of either IK screen or 1/2K screen formats. See '(. 
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LABEL 


LATEST 

LEAVE 

LFA 


cccc, 

cccc, -- addr 

At compilation time, creates a word cccc. At run time, cccc leaves 
the address of its pfa on the stack. Used to set up a pointer to the 
following area of memory, as for a machine language subroutine or a 
player image. Examples: 

Example 1: Player image 
2 BASE ! 

LABEL UPARROW 
00011000 C, 

00111100 C, 

01111110 C, 

00011000 C, 

00011000 C, 

00011000 c, 

OCX 


Example 2: Machine code two-times 
ASSEMBLER 

LABEL 2* 0 ,X ASL, 1 ,X ROL, RTS, 

— addr 

Leave the name field address of the topmost word in the CURRENT voca¬ 
bulary. 

C,L0 

Force termination of a DO-LOOP at the next opportunity by setting the 
loop limit equal to the current value of the index. The index itself 
remains unchanged, and execution proceeds normally until LOOP or +L00P 
is encountered. 

pfa — Ifa 

Convert the parameter field address of a dictionary definition to its 
link field address. 
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LIMIT 


LIST 

LIT 

LITERAL 

LOAD 

LOOP 

M* 

W 

M/MOD 

MAX 


-- n 

A constant leaving the address just above the highest memory available 
for a disc buffer. 

n — LO 

Display the ASCII text of screen n on the selected output device. 

SCR contains the screen number during and after this process. 

n C2,L0 

Within a colon-definition, LIT is automatically compiled before each 
16 bit literal number encountered in input text. Later execution of 
LIT causes the contents of the next dictionary address to be pushed 
to the stack. 

n — (compiling) P,C2,L0 

If compiling, then compile the stack value n as a 16 bit literal. 

This definition is immediate so that it will execute during a colon 
definition. The intended use is: 

: xxx C.calculateU LITERAL ; 

Compilation is suspended for the compile time calculation of a value. 
Compilation is resumed and LITERAL compiles this value. 

n — LO 

Begin interpretation of screen n. Loading will terminate at the end 
of the screen or at ;S. See ;S and —>. 

addr n -- (compiling) P,C2,L0 

Occurs in a colon-definition in form: 

DO ... LOOP 

At run-time, LOOP selectively controls branching back to the correspond¬ 
ing DO based on the loop index and limit. The loop index is incremented 
by one and compared to the limit. The branch back to DO occurs until 
the index equals or exceeds the limit; at that time, the parameters are 
discarded and execution continues ahead. 

At compile-time, LOOP compiles (LOOP) and used addr to calculate an 
offset to DO. n is used for error testing. 

nl n2 — d 

A mixed magnitude math operation which leaves the double number signed 
product of two signed numbers. 

d nl — n2 n3 

A mixed magnitude math operator which leaves the signed remainder 
n2 and signed quotient n3, from a double number dividend and divisor 
nl. The remainder takes its sign from the dividend. 

udl u2 — u3 ud4 

An unsigned mixed magnitude math operation which leaves a double quo¬ 
tient ud4 and remainder u3, from a double dividend udl and single 
divisor u2. 

nl n2 — max LO 

Leave the greater of two numbers. 
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MESSAGE n — 

Print on the selected output device the text of line n relative to 
screen 176 of drive 0. n may be positive or negative. MESSAGE may be 
used to print incidental text such as report headers. If WARNING is 
zero, the message will simply be printed as a number (disc unavailable). 


MIN nl n2 -- min L0 

Leave the smaller of two numbers. 

MINUS nl — n2 L0 

Leave the two ! s complement of a number. 

MOD nl n2 -- mod L0 

Leave the remainder of nl/n2, with the same sign as nl. 

MTB — V 

Alias of EMPTY-BUFFERS. 


NEXT 


NFA 

N00P 

NOT 

NUMBER 


0+S 

OFF 


-- addr 

This is the inner interpreter that uses the interpretive pointer IP 
to execute compiled Forth definitions. It is not directly executed, 
but is the return point for all code procedures. It acts by fetching 
the address pointed by IP, storing this value in register W. It then 
jumps to the address pointed to by the address pointed to by W. W 
points to the code field of a definition which contains the address 
of the code which executes for that definition. This usage of in¬ 
direct' threaded code is a major contributor to the power, portability, 
and extensibility of Forth. (Assembler Vocabulary) 

pfa -- nfa 

Convert the parameter field address of a definition to its name field. 

V 

A word that does nothing in minimal time. May be used for reserving 
space in a definition or as a null operation for a word that uses @EX. 
Generally for advanced programmers. Identical to TASK. Pronounced 

"no-op”. 

n — flag V 

Leaves a true flag if n is equal to 0. Otherwise, leaves a false flag. 

addr — d 

Convert a character string left at addr with a preceeding count, to 
a signed double number, using the current numeric base. If a decimal 
point is encountered in the text, its position will be given in DPL, 
but no other effect occurs. If numeric conversion is not possible, 
an error message will be given. 

start count — upper-1imit+1 lower-limit V 

Same as OVER + SWAP. Used to set up limits for DO LOOPs and the like. 

- 0 V 

A CONSTANT equal to 0. Used to enhance readability. 
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OFFSET 


ON 

OR 

OUT 

OVER 

PAD 

PFA 

PFLAG 

PICK 

POP 

PREV 

PROMPT 

PUSH 


-- addr U 

A user variable which may contain a block offset to disc drives. The 
contents of OFFSET is added to the stack number by BLOCK. Messages 
by MESSAGE are independent of OFFSET. See BLOCK, DRO, DR1, MESSAGE. 

— 1 y 

A CONSTANT equal to 1. Used to enhance readability. 

nl n2 -- or LO 

Leave the bit-wise logical or of two 16 bit values. 

-- addr U 

A user variable that contains a value incremented by EMIT. The user 
may alter and examine OUT to control display formatting. 

nl n2 -- nl n2 nl LO 

Copy the second stack value, placing it as the new top. 

— addr ' l_0 


Leave the address of the text output buffer, which is a fixed offset 
above HERE. 

nfa -- pfa 

Convert the name field address of a compiled definition to its para¬ 
meter field address. 

— addr y 

A variable that holds an output-select value. If bit 0 is set then 
output will be sent to the display screen. If bit 1 is set, then output 
will be sent to the printer. If both bits are set, then output will 
go to both channels. 

... n — ... nl V 

Copies the nth entry below n on stack to top of stack. 2 PICK is the 
same as OVER, 1 PICK is the same as DUP. 

-- addr 

The code sequence to remove a stack value and return to NEXT. POP is 
not directly executable, but is a Forth re-entry point after machine 
code. (Assembler Vocabulary) 

-- addr 

A variable containing the address of the disc buffer most recently 
referenced. The UPDATE command marks this buffer to be later written 
to disc. 


V 

Intended for system use only, in QUIT. A smart version of the usual 
." ok" in QUIT. Prevents "ok" and visible stack printout from being 
routed to printer. 

— addr 

This code sequence pushes machine registers to the computation stack 
and returns to NEXT. It is not directly executable, but is a Forth 
re-entry point after machine code. (Assembler Vocabulary) 
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PUT 


-- addr 

This code sequence stores machine register contents over the topmost 
computation stack value and returns to NEXT. It is not directly execu¬ 
table, but is a Forth re-entry point after machine code. 


QUERY 


QUIT 

R 

R# 

R/W 


R> 


RO 

REPEAT 


ROLL 

ROT 

RP! 


Input 80 characters of text (or until a "return") from the operators 
terminal. Text is positioned at the address contained in TIB with IN 
set to zero. 


Clear the return stack, stop compilation, and return control to the 
operators terminal. No message is given. 

— n 

Copy the top of the return stack to the computation stack. 

— addr U 

A user variable which may contain the location of an editing cursor, 
or other file related function. 

addr blk f — 

The fig-FORTH standard disc read-write linkage, addr specified is the 
source or destination block buffer, blk is the sequential number of 
the referenced block; and f is a flag for f=0 write and f=l read. 

R/W determines the location on mass storage, performs the read-write 

and performs any error checking. Important: See Note 1 at end of glossary. 

— " L0 

Remove the top value from the return stack and leave it on the compu¬ 
tation stack. See >R and R. 

-- addr U 

A user variable containing the initial location of the return stack. 
Pronounced R-zero. See RP! 

addr n — (compiling) P } C2 

Used within a colon-definition in the form: 

BEGIN ... WHILE ... REPEAT 

At run-time, REPEAT forces an unconditional branch back to just after 
the corresponding BEGIN. 

At compile-time, REPEAT compiles BRANCH and the offset from HERE to 
addr. n is used for error testing. 

... n -- ... V 

Moves the nth entry below n on stack to top of stack. 3 ROLL is the 
same as ROT, 2 ROLL is the same as SWAP. 0 ROLL is undefined. 

nl n2 n3 — n2 n3 nl LO 

Rotate the top three values on the stack, bringing the third to the 
top. 


A computer dependent procedure to initialize the return stack pointer 
from user variable RO. 
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RPICK 


n — V 

Copies nth entry on return stack to parameter (number) stack. For 
instance, 1 RPICK is the same as R and 2 RPICK is the same as I', 
etc. 


S->D 

SAVE 

SO 

SCR 

SGRCTL 

SIGN 

SMUDGE 

SP! 

SP@ 

SPACE 

SPACES 

SPEMIT 


n — d 

Sign extend a single number to form a double number. 


Gives prompt, and if answered with press of "Y" key, moves COLD and 
FENCE parameters to cover current system, makes Forth current, and 
creates a bootable copy of RAM-resident system up to HERE on disk in 
drive 1. 


— addr y 

A user variable that contains the initial value for the stack pointer. 
Pronounced S-zero. See SP! 

-- addr ' y 

A user variable containing the screen number most recently referenced 
by LIST. 


— addr V 

"Shadow Register" for GRACTL, the Atari graphics control register. 

See Atari Operating System Manual for explanation. 

n d — d LO 

Stores an ASCII sign just before a converted numeric output 
string in the text output buffer when n is negative, n is discarded, 
but double number d is maintained. Must be used between <# and #>. 


Used during word definition to toggle the "smudge bit" in a definitions’ 
name field. This prevents an uncompleted definition from being found 
during dictionary searches, until compiling is completed without error. 


A computer dependent procedure to initialize the stack pointer from SO. 
— addr 

A computer dependent procedure to return the address of the stack 
position to the top of the stack, as it was before SP@ was executed, 
(e.g. 1 2 SP@ @ . . . would type 2 2 1) 


Transmit an ASCII blank to the output device. 

n— LO 

Transmit n ASCII blanks to the output device. 

c V 

Like EMIT, but defined for Atari. Will output control codes as charac¬ 
ters instead of executing the controls. Used by EXPECT and other 
words. 
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STATE 

SWAP 

TASK 

THEN 

TIB 

TOGGLE 

TRAVERSE 


TRIAD 


— addr LO,U 

A user variable containing the compilation state. A non-zero value 
indicates compilation. The value itself may be implementation depen¬ 
dent. 


nl n2 -- n2 nl 

Exchange the top two values on the stack. 


LO 


A no-operation word which can mark the boundary between applications. 
By forgetting TASK and re-compiling, an application can be discarded 
in its entirety. 


P,C0,L0 

An alias for ENDIF. 

— addr U 

A user variable containing the address of the terminal input buffer. 

addr b — 

Complement the contents of addr by the bit battern b. 
addrl n — addr2 

Move across the name field of a fig-FORTH variable length name field, 
addrl is the address of either the length byte or the last letter. 

If n=l, the motion is toward hi memory; if n=-l, the motion is toward 
low memory. The addr2 resulting is address of the other end of the 
name. 


scr -- 

Display on the selected output device the three screens which include 
that numbered scr, beginning with a screen evenly divisible by three. 
Output is suitable for source text records, and includes a reference 
line at the bottom taken from line 14 of screen 177. 
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TYPE 


addr count — LO 

Transmit count characters from addr to the selected output device. 


TYPE as supplied zeroes out the high bit of each character before 
sending it to the output device, usually the screen or printer. 

If you want to be able to type all 8 bits for inverse characters, 
do the following: 

255 1 TYPE 20 + C! 

and return to 7 bit output by doing 

127 ' TYPE 20 + C! 

More generally, 

78TYPE < ' TYPE 14 + > C! ; 

7TYPE 127 78TYPE ; 

8TYPE 255 78TYPE ; 

(What you are doing with all of this is changing the mask that 
TYPE uses before executing EMIT.) 


U* 

U. 


ul u2 -- ud 

Leave the unsigned double number product of two unsigned numbers. 


n — 

Prints the number n in unsigned form. 


B 


U.R 


u n — B 

Prints unsigned number u right justified in a field n wide. 


U/ 


ud ul -- u2 u3 

Leave the unsigned remainder u2 and unsigned quotient u3 from the 
unsigned double dividend ud and unsigned divisor ul. 


U> 


u2 ul -- flag V 
Leaves true flag is u2 (unsigned) is greater than ul (unsigned). 
Otherwise, leaves false flag. 
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V 


u? 

UNTIL 

UPDATE 

USE 

USER 

VARIABLE 

VOC-LINK 

VOCABULARY 


addr — 

Does a @ from addr and an unsigned print of top of stack. 

f — (run-time) 
addr n — (compile) P,C2,L0 

Occurs within a colon-definition in the form: 

BEGIN ... UNTIL 

At run-time, UNTIL controls the conditional branch back to the 
corresponding BEGIN. If f is false, execution returns to just after 
BEGIN; if true, execution continues ahead. 

At compile-time, UNTIL compiles (OBRANCH) and an offset from HERE to 
addr. n is used for error tests. 


LO 

Marks the most recently referenced block (pointed to by PREV) as 
altered. The block will subsequently be transferred automatically to 
disc should its buffer be required for storage of a different block. 

— addr 

A variable containing the address of the block buffer to use next, as 
the least recently written. 

n - LO 

A defining word used in the form: 
n USER cccc 

which creates a user variable cccc. The parameter field of cccc 
contains n as a fixed offset relative to the user pointer register 
UP for this user variable. When cccc is later executed, it places 
the sum of its offset and the user area base address on the stack 
as the storage address of that particular variable. 

n " E,LU 

A defining work used in the form: 
n VARIABLE cccc 

When VARIABLE is executed, it creates the definition cccc with its 
parameter field initialized to n. When cccc is later executed, the 
address of its parameter field (containing n) is left on the stack, 
so that a fetch or store may access this location. 

— addr U 

A user variable containing the address of a field in the definition of 
the most recently created vocabulary. All vocabulary names are linked 
by these fields to allow control for FORGETting thru multiple vocabu¬ 
laries. 


E,L 

A defining word used in the form: 

VOCABULARY cccc 

to create a vocabulary definition cccc. Subsequent use of cccc will 
make it the CONTEXT vocabulary which is searched first by INTERPRET. 

The sequence "cccc DEFINITIONS" will also make cccc the CURRENT voca¬ 
bulary into which new definitions are placed. 

In fig-FORTH, cccc will be so chained as to include all definitions of 
the vocabulary in which cccc is itself defined. All vocabularies ulti¬ 
mately chain to Forth. By convention, vocabulary names are to be de¬ 
clared IMMEDIATE. See VOC-LINK. 
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VLIST 


List the names of the definitions in the context vocabulary. 


WAIT 

WARNING 


WHILE 


WIDTH 


WORD 


X 


XOR 

ok 


V 

Halts execution of Forth until a CONSOLE button is pressed. 

-- addr U 

A user variable containing a value controlling messages. If = 1 
disc is present, and screen 176 of drive 0 is the base location for 
messages. If = 0, no disc is present and messages will be presented 
by number. If = -1, execute (ABORT) for a user specified procedure. 
See MESSAGE, ERROR. 

f — (run-time) 

adl nl -- adl nl ad2 n2 p,C2 

Occurs in a colon-definition in the form: 

BEGIN ... WHILE (tp) ... REPEAT 
At run-time, WHILE selects conditional execution based on boolean 
flag f. If f is true (-non-zero), WHILE continues execution of the 
true part thru to REPEAT, which then branches back to BEGIN. If f 
is false (zero), execution skips to just after REPEAT, exiting the 
structure. 

At compile time, WHILE emplaces (OBRANCH) and leaves ad2 of the re¬ 
served offset. The stack value will be resolved by REPEAT. 

— addr U 

In fig-FORTH, a user variable containing the maximum number of letters 
saved in the compilation of a definitions' name. It must be 1 thru 
31, with a default value of 31. The name character count and its 
natural characters are saved, up to the value in WIDTH. The value may 
be changed at any time within the above limits. 

c — L0 

Read the next text characters from the input stream being interpreted, 
until a delimiter c is found, storing the packed character string 
beginning at the dictionary buffer HERE. WORD leaves the character 
count in the first byte, the characters, and ends with two or more 
blanks. Leading occurances of c are ignored. If BLK is zero, text 
is taken from the terminal input buffer, otherwise from the disc 
block stored in BLK. See BLK, IN. 


This is pseudonym for the "null" or dictionary entry for a name of 
one character of ASCII null. It is the execution procedure to termi¬ 
nate interpretation of a line of text from the terminal or within a 
disc buffer, as both buffers always have a null at the end. 

nl n2 — xor LI 

Leave the bit-wise logical exclusive-or of two values. 

V 

Does three backspaces. When using "logical line input" from keyboard 
to re-input previously entered line, this word gives harmless meaning 
to the old "ok" prompt Forth may find in the input stream. See "logical 
line input" section in Strolling through ValForth. 
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Used in a colon-definition in form: 5 

: xxx E words ] more ; 

Suspend compilation. The words afterCare executed, not compiled. 
This allows calculation or compilation exceptions before resumina 
compilation with ]. See LITERAL, 3 . 

(Compile] -- p c 

Used in a colon-definition in form: 

: xxx [COMPILE] FORTH ; 

[COMPILE] will force the compilation of an immediate definition, that 
would otherwise execute during compilation. The above example will 
select the FORTH vocabulary when xxx executes, rather than at compile 


Resume compilation, to the completion of a colon-definition. See [. 


NOTES: 

Note 1 

Due to a bug in at least some of the Atari Operating System ROM programs, 
a sector may not be written directly from a memory area in which the low 
byte of the bottom location is $7F. The system will hang if this is 

attempted. This is not a valFORTH bug, it is Atari's. Please watch out 
for it. 


V-27 




va/FOJfFI# Memory Map 


STANDARD DISPLAY 
MEMORY AREA 


DP 

LIMIT 

FIRST 
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KERNEL 



BOOT CODE 
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UP 

RO 

IN 
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valFORTH 6502 Assembler 


Overview 

Most programming applications can be undertaken completely in high 
level FORTH. There are times, due to speed constraints, when assembly language 
must be used. Typically, "number crunching" and high speed graphic routines 
must be machine coded, valFORTH provides a powerful 6502 FORTH assembler 
for these special occasions. 

FORTH assemblers differ from standard assemblers by making the best use 
of the stack and the FORTH system as a whole. The FORTH assembler is smaller 
than a standard assembler. In the case of the valFORTH assembler, this is 
particularly true. 

The valFORTH assembler offers the programmer the following improvements 
over a standard assembler: 

1) IF...THEN...ELSE structures which use positive logic 
rather than negative logic. 

2) BEGIN...UNTIL structures for post-testing indefinite 
loops. 

3) WHILE...REPEAT structures for pre-testing indefinite 
loops. 

4) BEGIN...AGAIN structures for unconditional looping. 

5) Full access to the FORTH operating system and its 
capabilities such as changing bases. 

6) Complex assembly time calculations. 

7) Mixed high level FORTH with assembly code to take 
full advantage of each. 

8) Full macro capability. 

The following is a complete description of the valFORTH assembler. This 
description assumes a working knowledge of 6502 assembly language programming 
and related terms. 

The purpose of the FORTH assembler is to allow machine language programming 
without the need to abandon the FORTH system. Words coded in assembly language 
must follow the standard FORTH dictionary format and must adhere to certain 
guidelines regarding their coding. 

Assembly language programmers typically have two methods of storing 
programs into RAM. The machine code can be poked directly into memory, or an 
assembler can be used to accomplish this. The former method is brutal, but it 
has the advantage that precious memory is not taken up by the assembler. The 
drawback, of course, is loss of readability and ease of modification. FORTH 
allows both of these methods to be employed. 
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The words V and "C," can be used to poke any machine language program 
into the dictionary. This is used only when memory restrictions prohibit the 
use of an assembler or if it is assumed that no assembler is available. 

In high level FORTH, words are compiled into the dictionary using the 
following form: 


: name high-level-FORTH... ; 

When compiling a machine coded word, this becomes: 

CODE name machine-code... C; 

In this example, the word "CODE" creates a header for the next word in 
much the same way creates a header. The difference lies in the fact that 
informs the system that the following definition is high level FORTH, while 
"CODE" indicates that the definition is a machine or assembly language 
definition. In the same manner,'";" terminates a high level FORTH definition 
while "C;" terminates a code definition. 

To clarify this, a code definition will be programmed that will clear the 
top line of the current video display on an Atari 800 microcomputer. Note that 
video memory is pointed to by the address stored in locations 88 and 89 (decimal). 
The 6502 code is shown in listing 1. 


CLR 

TYA 

; Y comes in with 0; 0 means a blank 


LDY #39 

; 40 characters/line (0 thru 39) 

LOOP 

STA (88), Y 

; Fill from end to beginning 


DEY 

; Done? 


BPL LOOP 

; Keep going if not 


JMP NEXT 

; Re-enter the FORTH operating system 



Listing 1 

The CODE definition 

equivalent to listing 1 would be: 


HEX 

(put in hex mode) 


CODE CLR 

(define code word) 


98 C, 

(poke in code) 


AO C, 

27 C, 


91 C, 
88 C, 
10 C, 

58 C, <1—j 

FB C, —f 


C; DECIMAL 

(end assembly) 


First, the FORTH system is put into the hexadecimal mode so that opcode 
values need not be converted to decimal. Next, the word CODE puts the system 
into an assembly mode and enters the new word CLR into the dictionary as a 
machine language word. The opcodes are then byte compiled ("C,") into the 
dictionary. Note that for the final jump to re-enter FORTH, the predefined 
word NEXT was word compiled into the dictionary. The word C; terminates 

the assembly process. The system is then restored to the decimal mode. 
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This method can always be used, but it is very tedious. Each opcode must 
be looked up, and all relative branches calculated. Besides introducing a 
great source for error, if a single opcode is added or deleted, it is possible 
that many jumps must be re-calculated. For this reason, using the assembler 
is the prescribed method for entering machine language routines. 

Unlike the standard assembler which has four fields (the label field, 
the operation field, the operand field, and the comment field), the FORTH 
assembler has only three fields. In a FORTH assembler, there is no explicit 
label field, but there is an implied label field through the use of the assembler 
constructs IF, and BEGIN, described later. In addition, the remaining three 
fields in the FORTH assembler are in reversed order (as is standard for the 
FORTH language). In other words, the operand precedes the operation, and 
remarks can be embedded anywhere. .. 

In compiling an assembly word, the FORTH assembler ultimately uses either 
or "C," and for this reason assembly mnemonics traditionally end with a 
comma, valFORTH equivalents are shown in chart 1. 


Standard Assembler 


valFORTH 

Assembl 

LDX COUNT 


COUNT 

LDX, 

JMP COUNT+1 


COUNT 

1+ JMP, 

LDA #3 


# 3 

LDA, 

ADC N 


N 

ADC, 

STY TOP ,X 


TOP ,X 

STY, 

INC B0T,Y 


BOT ,Y 

INC, 

STA (TOP,X) 


TOP X) 

STA, 

AND (BOT),Y 


BOT ) Y 

AND, 

JMP (POINT) 


POINT 

) JMP, 

DEC N+4 


N 4 + 

DEC, 

DEX 



DEX, 

ROL A 


.A 

ROL, 


or 


ROL.A, 

Note: # 9 LDA, = 

9 # 

LDA, 


TOP ,X ROL, = 

,X TOP 

ROL, etc. 



Chart 1 


Converting the program given in listing 1 to FORTH assembly mnemonics 
we have: 

DECIMAL 


CLR 

TYA, 

( 

TYA 

) 

# 39 LDY, 

( 

LDY m 

) 

BEGIN, 

( LOOP 

) 

88 )Y STA, 

( 

STA (88) ,Y 

) 

DEY, 

( 

DEY 

) 

MI UNTIL, 

( 

BPL LOOP 

) 

NEXT JMP, 

( 

JMP NEXT 

) 


C; 
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In the above example, a BEGIN ... UNTIL, clause (described in the next 
section) is used. By using this structure, no labels are necessary and positive 
logic is used rather than negative logic (i.e., "repeat until minus" instead 
of "if NOT minus, then repeat"). Note that the FORTH assembler compiles 
exactly the same machine code as the standard assembler, it simply makes the 
assembly coding easier. 


Control Structures 


Allowing labels within assembly language programming would make the FORTH 
assembler needlessly long and slow. To get around the problem of test branching, 
the ValFORTH assembler has a very powerful set of control structures similar to 
those found in high level FORTH. 


The IF,...ENDIF, and IF,...ELSE,...ENDIF, clauses 


The IF, construct which handles conditional downward branches has the 
following two forms: 


...code... 
flag IF, 

...true code... 
ENDIF, 

...code... 


...code... 
flag IF, 

...true code... 
ELSE, 

...false code... 
ENDIF, 

...code... 


where "flag" is one of the 6502 statuses: NE , EQ , CC , CS , VC , VS , 

MI , or PL. The following are a few examples of how these are used. 

Note: When the FORTH inner interpreter passes control to an assembly language 
routine, the Y register always contains a zero value and the X register must 

be preserved as it is used by the FORTH system to maintain the parameter stack. 

See the section on parameter passing for more information. 


; Code routine for 1+ 


ONEPL INC 0,X 
BNE THERE 
INC 1,X 
THERE JMP NEXT 


; increment low byte of 16 bit value 
; carry out of low? 

; increment high byte if so 
; re-enter FORTH system 


Now in ValFORTH assembly language: 


CODE ONEPL 

0 ,X INC, 

EQ IF, 

1 ,X INC, 
ENDIF, 

NEXT JMP, 

C; 


(define word) 

(increment low byte) 

(if result was zero,) 
(then bump the high byte) 

(exit to FORTH) 
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Note: In the following example, CONIN is assumed to be predefined. 


; Input routine 
INPUT JSR CONIN 
CMP #$0D 
BNE INP1 
...codel... 
JMP INP2 

INP1 ...code2... 
INP2 ...code3... 
JMP NEXT 


; Go get character, comes back in A 
; Is it a carriage return? 

; If not, do something else 
; execute code for carriage return 
; do not execute "normal" code 
; execute code for normal keys 
; execute code more common code 
; re-enter FORTH system 


The equivalent valFORTH version would be: 


HEX 

CODE INPUT 

CONIN JSR 
# OD CMP, 

EQ IF, 

...codel... 
ELSE, 

...code2... 
ENDIF, 

...code3... 
NEXT JMP, 

C; DECIMAL 


(Get character ) 
(carriage return? } 
(If so, then ) 
(execute c/r code ) 
(otherwise ) 


(execute normal code ) 


(re-enter FORTH system ) 


The BEGIN,...UNTIL, clause 

Another useful structure is the BEGIN,...UNTIL, construct which allows 
for post-testing indefinite looping. The BEGIN,...UNTIL, construct has the 
following form: 

...codel... 

BEGIN, code2 is repeatedly 

...code2... executed until "flag" 

flag UNTIL, is true. 

...code3... 


The following 6502 routine waits until a carriage return has been typed. 


i WAIT until c/r 
WAIT JSR CONIN 
CMP #$0D 
BNE WAIT 
JMP NEXT 


; Go get a character, comes back in A 
; Is it a carriage return? 

; Ask again if not 
; Return to FORTH 


Using the BEGIN, clause, 
NEXT 

CODE WAIT 
BEGIN, 

CONIN JSR, 
# OD CMP, 
EQ UNTIL, 

NEXT JMP, 

C; DECIMAL 


this becomes 


(Code name WAIT ) 
(Begin waiting ) 
(Get a character ) 
(Carriage return?) 
(loop up until so) 
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The BEGIN,...WHILE,...REPEAT, clause 

In the valFORTH assembler, there is another valuable control structure. 
It is the BEGIN,...WHILE,...REPEAT, structure. The WHILE, clause allows pre¬ 
testing indefinite loops to be easily programmed. It takes the form: 


...codel... 
BEGIN, 

...code2... 
flag WHILE, 

...code3... 
REPEAT, 

...code4... 


Code2 and code3 are repeatedly 
executed until "flag" become 
false, at which time program 
control proceeds to code4. 


A common example of the WHILE, clause is getting a line of input text terminated 
by a carriage return. 


; Get line of text 
GETLN JSR CONIN 
CMP #$0D 
BEQ GETL1 
STA BFFR,Y 
INY 

JMP GETLN 
GETL1 JMP NEXT 


(note: Y=0 on entry always) 
; Get one character 
; C/R terminates input 
; If not a C/R then 
; store the character 
; Bump buffer pointer 
; Go back for more 
; Exit to FORTH 


Using the WHILE, clause in valFORTH, we have: 


HEX 

CODE GETLN 
BEGIN, 

CONIN JSR, 

# OD CMP, 

NE WHILE, 

BFFR ,Y STA, 
INY, 

REPEAT, 

NEXT JMP, 

C; DECIMAL 


(Get a character ) 
(Carriage return? ) 
(If not, ) 
(then store the character ) 
(and bump the pointer ) 
(Repeat all of the above ) 
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The BEGIN,...AGAIN, clause 

The final control structure is the BEGIN,...AGAIN, structure. This 
structure allows the use of unconditional looping in assembly language routines. 
Although its use is rare, it can reduce code size considerably. It takes the 
following form: 


...codel... 

BEGIN, 

...code2,.. 
flag IF, 

...code3... 
re-entry-point JMP, 
ENDIF, 

...code4... 

AGAIN, C; 


Repeatedly execute code2 
and code4 until "flag” 
becomes true, in which 
case, program execution 
continues with code3 and 
a system re-entry made. 


The best example of the AGAIN, clause is in the coding of the CMOVE routine: 


; Byte at a time front end memory move 


CMOVE IDA #3 

JSR SETUP 
CM0V1 CPY N 

BNE CM0V2 
DEC N+l 
BPL CM0V2 
JMP NEXT 

CM0V2 LDA (N+4),Y 
STA (N+2),Y 
INY 

BNE CM0V1 
INC N+5 
INC N+3 
JMP CM0V1 

Using the AGAIN, clause, this 


; Get top three stack items 
; Move them to N scratch area 
; Time to decrement COUNT high? 
; Nope 

; Yes, so do it 
; Bypass exit if not done 
; Exit to FORTH system 
; Get byte to move 
; Move it! 

; Bump byte pointer 
; Keep going until ready to 
; bump high bytes of both 

; "to" and "from" addresses 

; Do it all again 

becomes: 


CODE CMOVE 
# 3 LDA, 

SETUP JSR, 

BEGIN, 

BEGIN, 

N CPY, 

EQ IF, 

N 1+ DEC, 

MI IF, 

NEXT JMP, 
ENDIF, 

ENDIF, 

N 4 + )Y LDA, 

N 2+ )Y STA, 
INY, 

EQ UNTIL, 

N 5 + INC, 

N 3 + INC, 

AGAIN, 

C; DECIMAL 


(Prepare for memory move) 

(Start the process) 
(done?) 

(Maybe, keep checking) 
(Re-enter FORTH system) 

(Get byte to copy) 

(Store in new location) 
(Bump pointer) 

(Bump addresses) 

(Do it all again) 
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Parameter Passing 

One of the most useful features of the FORTH language is its ability to 
use a parameter stack for passing values from one word to another. For 
assembly language routines to really be useful in the FORTH system, there must 
be some facility for these routines to access this stack. Likewise, there 
should be some way in which to access the return stack as well. This section 
details exactly how to make the best use of both stacks. 

Since the FORTH system maintains dual stacks and the 6502 supports only 
one, it is necessary to simulate one of the stacks. For ease of stack manipu¬ 
lation, the parameter "is simulated; the return stack uses the hardware stack 
of the microprocessor. 


The simulated stack uses the 0-page,X addressing mode of the 6502. 

For example, the following statements show how the parameter stack is organized. 


LDA 0,X 
INC 1,X 
ADC 2,X 
EOR 3,X 
RNL 4,X 
AND 5,X 


Low byte of item on top of stack 

High byte of top item 

Low byte of item second on stack 

High byte of 20S 

Low byte of item third on stack 

etc. 


In high level FORTH, the word DROP drops (or pops) the top value from 
the stack. The code definition for DROP is: 


CODE DROP INX, INX, NEXT JMP, C; 

In the same way, values can be "pushed" to the stack. Note that the X register 
must be preserved between FORTH words or the parameter stack is lost! Thus if 
the X register is needed in a code "definition, it must be saved upon entry to 
the routine and restored before returning to the FORTH system. The special 
location XSAVE is reserved for this: (The word XSAVE has been defined as a 
FORTH constant.) 

STX XSAVE Save the X register 

LDX XSAVE Restore the X register 

In all the examples given so far, the code definitions have re-entered 
the FORTH system through the normal re-entry point called NEXT. The following 
is a complete description of all possible re-entry points: (In all of the 
following code examples, standard 6502 assembler format has been used for ease 
of comprehension. All valFORTH assembler equivalents can be found in appendix A.) 

The NEXT re-entry point 

The NEXT routine transfers control to the next FORTH word to be 
executed. All FORTH words eventually come through the NEXT routine. 

Likewise, all other re-entry points come through NEXT once they have com¬ 
pleted their special tasks. The next routine is typically used by words 
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The NEXT re-entry point (cont'd) 


such as 1- which do not modify the number of arguments on the 
stack. The word NEXT is defined as a FORTH constant. NXT, is an 
abbreviation for NEXT JMP, . 


Example: ; 1- routine 

ONEM LDA 0,X 
BNE 0NE1 
DEC 1,X 
0NE1 DEC 0,X 
JMP NEXT 


; Borrow from low byte? 

; If not, ignore correction 
; Decrement high byte 
; Now do the low 
; Re-enter FORTH 


Listing 2 


The PUSH re-entry point : 

The PUSH routine pushes a 16 bit value to the parameter stack whose 
low byte is found on the 6502 return stack and whose high byte is found 
in the accummulator. The X register is automatically decremented twice 
for the two bytes. This routine is typically used for words such as 
OVER or DUP which leave one more argument than they expect. The word 
PUSH has been defined as a FORTH constant. PSH, is an abbreviation 
for PUSH JMP, • 


Example: ; DUP routine 

DUP LDA 0,X 
PHA 

LDA 1,X 
JMP PUSH 


; Get low byte of TOS 
; Push it 

; Put high byte in A 
; Put it on the P-stack 


Listing 3 


The PUT re-entry point : 

The PUT routine replaces the value currently on top of the parameter 
stack with the 16 bit value whose low byte is found on the 6502 stack and 
whose high byte is in the accumulator. This is used by words such as ROT 
or SWAP which do not change the number of values on the stack. The word 
PUT has been defined as a FORTH constant. PUT, is an abbreviation for 


PUT JMP, 

• 


Example: 

; SWAP routine 



SWAP LDA 2,X 

; Low byte of 2nd value 


PHA 

; Save it 


LDA 0,X 

; Put low byte of TOS 


STA 2,X 

; into low byte of 20S 


LDA 3,X 

; Hold high byte of 20S 


LDY 1,X 

; Put high byte of TOS 


STY 3,X 

; into high byte of 20S 


JMP PUT 

; Replace TOS no 


Listing 4 
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The PUSHOA re-entry point 

The PUSHOA re-entry point pushes the 8 bit unsigned value in the 
accumulator as a 16 bit value with the upper 8 bits zeroed. This word is 
very commonly used by words which leave a boolean flag on the parameter 
stack such as 7TERMINAL. The word PUSHOA has been defined as a FORTH 
constant. PSHA, is an abbreviation for PUSHOA JMP, . 


Example: 


; 7TERMINAL routine 


QTERM LDA $D01F 
EOR #7 
BEQ QT1 
INY 

QT1 TYA 

JMP PUSHOA 


; Read Atari CONSOLE keys 
; Anything pressed? 

; If not, go push false 
; Else push a true 
; Put Y (0 or 1) in A 
; Go push the result 


Listing 5 


The PUTOA re-entry point : 

The PUTOA routine replaces the value currently on top of the parameter 
stack with the 16 bit value whose low byte is in the accumulator and whose 
high byte is set to zero. This is used by words such as C@ which simply 
replace their arguments on the stack. The word PUTOA is defined as a FORTH 
constant. PUTA, is an abbreviation for PUTOA JMP, . 

Example: ; Byte fetch 

CFCH LDA (0,X) ; Load byte indirectly 

JMP PUTOA ; Replace the address 
; with the contents 

Listing 6 

The BINARY re-entry point 

The BINARY re-entry point drops the value on top of the parameter 
stack and then performs the PUT operation described above. This word is 
commonly used by words such as XOR which use one more argument than they 
leave. The word BINARY has been defined as a FORTH constant. 


Example: 


; Exclusive or TOS with 20S 


LDA 

0,X 

; Get low byte of 

EOR 

2,X 

; XOR it with low 

PHA 


; Save it 

LDA 

1,X 

; Now do same for 

EOR 

3,X 

; Result in A 

JMP 

BINARY 

; Go DROP , PUT 


top value 
of 2OS 

high bytes 


Listing 7 
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POP and POPTWO re-entry points 

The POP and POPTWO re-entry points are used when values must be 
dropped from the parameter stack. POP performs a DROP, while POPTWO 
performs a 2DR0P. Most words which can use BINARY can use POP. The words 
POP and POPTWO have been defined as FORTH constants. POP, is an 
abbreviation for POP JMP, and POP2, is an abbreviation for POPTWO JMP, . 


routine 

; Get low byte 
; XOR with other low byte 
; Put directly on stack 
; Do the same for high bytes 


Examples: ; Another XOR 
XOR LDA 0,X 
EOR 2,X 
STA 2,X 
LDA 1,X 
EOR 3,X 
STA 3,X 
JMP POP 


; Remove unneeded TOS item 


Listing 8 


; C! routine 

CSTR LDA 2,X ; Get byte to store 

STA (0,X) ; Store it! 

JMP POPTWO ; Drop byte and address 


Listing 9 


The SETUP routine 


A very useful routine in the FORTH system is the code routine SETUP. 

On the 6502, 0-page addressing is typically faster than absolute address¬ 
ing. Also, some instructions, such as indirect-indexed addressing, can use 
only 0-page addresses. The SETUP routine allows the assembly language 
programmer to transfer up to four stack values to a scratch pad in the 
0-page for these operations. The predefined name for this area is N. 

The calling sequence for the SETUP routine is: 

LDA #nu’m ; Move "num" values to N, ("num" = 1-4} 

JSR SETUP ; then drop "num" values from the stack 


The SETUP routine moves one to four values to the N scratch area 
and drops all values moved from the parameter stack. These values are 
stored in the following order: 


LDA N 
EOR N+l 
ADC N+2 
STY N+3 
INC N+4 


; Low byte of value that was TOS 
; High byte ( N 1+ EOR, ) 

; Low byte of value that was 20S 
; High byte ( N 3 + STY, ) 

; Low byte of 305 ( N 4 + INC, ) 


DEC N+7 


High byte of value that was 40S 


Words such as CMOVE and FILL which use indirect-indexed addressing 
typically use the SETUP routine (see the BEGIN,...AGAIN, example). The 
word SETUP has been defined as a FORTH constant. 
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Return stack manipulation 

The FORTH return stack is implemented as the normal 6502 hardware 
stack. To push and pop values, the 6502 stack instructions PHA and PLA 
can be used. Sometimes it is also necessary to manipulate the data on the 
return stack (such as for DO looping). Using the normal stack operations 
to do this can be tedious. Using indexed addressing, the return stack 
can be manipulated in the same manner as the parameter stack. 


Examples: ; >R routine 
TOR LDA 1,X 
PHA 

LDA 0,X 
PHA 

JMP POP 


; 3rd loop index 
K STX XSAVE 
TSX 

LDA $109,X 
PHA 

LDA $10A,X 
LDX XSAVE 
JMP PUSH 


; Pick up high byte 
; Push it to R 
j Now do the low byte 
; It's done! 

; Now, "lose" TOS 

Listing 10 

(I > I' ,J , ... K) 

; Save P-stack pointer 
; Get R-stack pointer 
; 101-102,...,109-10A, (L-H) 
; Push low byte of 3rd item 
; A now has high byte 
; Restore P-stack pointer 
; Push the index 

Listing 11 


Machine Language Subroutines in valFORTH 


When coding in assembly language, it is often useful to be able to make 
subroutine calls for often used operations. Using CODE makes it possible to 
do this, but it is not recommended. The following subroutine uses CODE. 


CODE S1+ 

0 ,X INC, 

EQ IF, 

1 ,X INC, 
ENDIF, 

RTS, 

C; 


( Subroutine 1+ ) 
( INC 0,X ) 
( BNE *+4 ) 
( INC 1,X ) 

( ) 

( RTS ) 


This subroutine could now be used in assembly language routines in the follow¬ 
ing way: 

CODE 1+ (Another 1+ routine ) 

' S1+ JSR, ( JSR S1+ ) 

NEXT JMP, ( JMP NEXT ) 

C; 
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This works fine, but there is one slight problem. If the user types S1+ as a 
command (i.e., it is not called, but executed) the FORTH system will "crash" 
when the RTS statement is encountered. This is because FORTH does not call its 
words, but jumps to them. For this reason, CODE is not used. A word which 
acts like CODE but protects the system is needed. 

In the code for 1+ above, it was necessary to ' (tick) the subroutine to 
find its address. It would be desirable if we could simply type its name and 
have it return its address (just as NEXT and PUSH do). This is possible. The 
word SUBROUTINE below allows this (note that this word is not automatically 
loaded with the assembler, it must be typed in by the user). 


SUBROUTINE 
0 VARIABLE 
-2 ALLOT 

[COMPILE] ASSEMBLER 
?EXEC !CSP ; 


(new word SUBROUTINE ) 
(is like a VARIABLE ) 
(discard the value of 0 ) 
(Put into assembly mode ) 
(Set/check for errors ) 


The word SUBROUTINE can be used in the same way CODE is except that 
SUBROUTINES end with an RTS instruction while CODE routines must end with a 
jump to a re-entry point. When the word defined using SUBROUTINE is executed, 
the entry point to the routine is left on the stack similar to the way in which 
a word defined using VARIABLE leaves an address. The following is an example 
of subroutine usage. 


SUBROUTINE 2'SCOMP 
SEC, 

# LDA, 

,X SBC, 


0 
0 

0 ,X STA, 
0 
1 
1 

RTS. 


LDA, 
,X SBC, 
,X STA, 


C; 


(Two's complement ) 
(routine ) 

(i.e., TOS => - TOS) 


It can now be used as such: 


CODE ABS 

1 ,X LDA, 

MI IF, 

2'SCOMP JSR, 
ENDIF, 

NEXT JMP, 


(Take abs. value of TOS ) 
(Is TOS < 0 ? ) 

(If so, TOS => -TOS ) 

(Exit to FORTH system ) 


When the new word 2'SCOMP is executed directly, it leaves its address 
on the stack. When it is called by a subroutine, it performs a two's comple¬ 
ment on the top stack value. This dual type of execution allows safe access 
to assembly language subroutines. 
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Macro Assemblies in valFORTH 


FORTH assemblers use a reversed form of notation so that all the benefits 
of the standard FORTH system are available. In other words, anything that can 
be done in FORTH can be done during assembly time in a code definition. This 
is because all of the assembler opcodes are actually FORTH words which take 
arguments from the parameter stack. Thus 


NEXT JMP, 

actually puts the address of the NEXT routine (NEXT is a FORTH constant) onto 
the parameter stack. The word JMP, then compiles the address into the dictionary. 
Here is a simplified definition (it does not test for indirect jumping) for the 
JMP, opcode: 

HEX 
: JMP, 

4C C, 

; DECIMAL 

All assembly words are designed in this fashion. Thus the necessity for 
operands to precede opcodes becomes clear. This allows the use of complex 
assembly time calculations that no ordinary assembler would ever support (e.g. 
no standard 6502 assembler would allow the use of the SIN function for generat¬ 
ing a data table). 


(address — ) 

(compile in JMP opcode ) 
(compile in the address ) 


Most assemblers do allow the use of the basic operations: 
and &. These are easily used in the valFORTH system: 


LDA #C0UNT&$FF 
LDY #NAME/$100 
EOR N+6 
LDX #"A"+$80 
etc. 


COUNT FF AND * LDA, 
COUNT 100 / # LQY, 

N 6 + EOR, 
ASCII A 80 + # LDX, 


The looping structures IF, and BEGIN, each leave two values on the stack 
during assembly time. The first is a branch address, the second is an identifi¬ 
cation code. When ENDIF, is executed, it checks the identification code to 
verify that structures have not been illegally interleaved (i.e., BEGIN, ... 
ENDIF, ). If everything checks out, ENDIF, then calculates the branch offset 
required by the IF, clause, otherwise an error is reported. The BEGIN, clause 
functions in the same manner. Thus, the words IF, and BEGIN, are predefined 
macro instructions in the valFORTH assembler. 


The fact that a-FORTH assembler is nothing but a collection of words means 
that the assembler, like the FORTH language itself, is extensible. In other 
words, macro assemblies can easily be performed by defining new assembler 
directives. Take the following code extract which outputs a text string: 
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...code... 

JSR CRLF 
JSR PRTXT 

.BYTE 11,'valFORTH 1.' 
LDA REL 
JSR PRTNM 
JSR CRLF 
...code... 


; Skip to next line 
; Call print routine 
; String to output 
; Get release number 
; Print the number 
; Issue c/r 


This code prints out the string "valFORTH 1.x" where "x" is the release 
number. Note that the routine PRTXT does not exist, it is simply used here 
for example purposes. The PRTXT routine "pops" the return address which points 
to the output string, picks up the length byte and adds it to the return address. 
The return address, which now points to the LDA instruction is "pushed" back 
onto the stack. The PRTXT routine still has a pointer to the string which it 
then prints out. Finally, it dones an RTS and returns control to the calling 
program. The release number is then printed out. 


Assuming that the PRTXT routine is used quite often, it would be desirable 
to make it an assembler macro. A word which automatically assembles in the 
subroutine call to PRTXT and then assembles in a user specified string would be 
quite handy. In valFORTH, this is easily accomplished: 


ASSEMBLER DEFINITIONS 
HEX 

: PRINT" 

20 C, PRTXT , 

22 WORD 

HERE C@ 1+ ALLOT 
; DECIMAL 
IMMEDIATE 
FORTH DEFINITIONS 


(This is an assembler word) 
(Put system in base 16) 
(Command form: PRINT" text") 
(compile in JSR PRTXT) 

(Now the string upto ") 

(Bump dictionary pointer) 

(all done,) 

(make word execute even at) 
(compile time.) 


This word could now be used in ValFORTH assemblies in the following manner: 

...code... 

CRLF JSR, 

PRINT" ValFORTH 1." 

REL LDA, 

PRTNM JSR, 

CRLF JSR, 

...code... 

Using the newly defined PRINT" macro, strings no longer need to be counted, 
and since there is less text to enter, typing errors are reduced. Other useful 
macros which could be designed are words which allow conditional assembly or 
automatically set up I0CB blocks for Atari operating system calls. Experienced 
assembly language programmers typically have a set of often used routines 
defined as macro instructions for quicker program development. 


(Skip to next line) 
(Print out string) 
(Get release number) 
(Go print it) 

(Skip to next line) 
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Compatability With Other Popular Assemblers 

There are several other versions of FORTH out which have 6502 assemblers. 
The two major versions are the Forth Interest Group's written by William 
Ragsdale, and the version put out by the Atari Program Exchange written by 
Patrick Mullarky. The valFORTH assembler is a superset of both of these fine 
assemblers and is fully compatible with both versions . 

Although not stated previously in the documentation, there are several 
ways in which to implement the IF, , WHILE, and UNTIL, structures. The 
valFORTH assembler was designed with transportability in mind. Although the 
recommended method is the valFORTH version, each of the following may be used . 


valFORTH 

Fig version 

APX version 

EQ IF, 

' 0= IF, 

IFEQ, 

NE IF, 

0= NOT IF, 

IFNE, 

CS IF, 

CS IF, 

IFCS, 

CC IF, 

CS NOT IF, 

IFCC, 

VS IF, 


IFVS, 

VC IF, 


IFVC, 

MI IF, 

0< IF, 

IFMI, 

PL IF, 

0< NOT IF, 

IFPL, 

EQ WHILE, 

NE WHILE, 

CC WHILE, 

CC WHILE, 

VS WHILE, 

VC WHILE, 

MI WHILE, 



PL WHILE, 

EQ UNTIL, 

0= UNTIL, 

0= UNTIL, 

NE UNTIL, 

0= NOT UNTIL, 

0= NOT UNTIL, 

CS UNTIL, 

CS UNTIL, 


CC UNTIL, 

CS NOT UNTIL, 


VS UNTIL, 



VC UNTIL, 

MI UNTIL, 

0< UNTIL, 


PL UNTIL, 

0< NOT UNTIL, 



Chart 2 
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In all versions, the word END, is synonymous with the word UNTIL,. Likewise 
THEN, is synonymous with ENDIF,. 

In the valFORTH and Fig assemblers, compiler security is performed to give 
added protection to the user against assembly errors. To accomplish this, the 
word C; or its synonym END-CODE is used to terminate the assembly word and 
perform the check. To remain compatible with APX FORTH, C; is not required in 
this release of valFORTH. However, it is strongly recommended that C; be 
used. Although C; and END-CODE are identical, C; is used in-house at Valpar 
for brevity. (Note that in later releases of valFORTH, C; will become mandatory) 

There are several ways in which the indirect jump in the 6502 architecture 
is implemented in FORTH assemblers. The valFORTH assembler supports three 
common versions. Thus, 


JMP (VECTOR) 

can be: 

VECTOR )JMP, 

VECTOR ) JMP, 
or VECTOR JMP(), 

It is recommended that the first version be used. 

It must be remembered that valFORTH's additional constructs may not be 
recognized by assemblers available from other vendors. If assembly listings 
are to be published for general 6502 FORTH users, it is suggested that valFORTH's 
advanced features not be used so that novice programmers can still make use of 
valuable pieces of code. 



valFORTH 6502 Assembler 


Appendix A valFORTH Code Equivalents 

This appendix gives the valFORTH assembly code for all 6502 code listings 
which are marked. Although listing 1 has already been translated to valFORTH 
assembly code, it is reproduced here for completeness. 


Listing 1 


DECIMAL 
CODE CLR 
TYA, 


C; 

Listing 2 
CODE 


# 39 LDY, 
BEGIN, 

88 )Y STA, 
DEY, 

MI UNTIL, 

NEXT JMP, 


0 ,X LDA, 

NE IF, 

1 ,X DEC, 
ENDIF, 

0 ,X DEC, 
NEXT JMP, 


(Move a blank [0] into A) 
(Move count into Y) 

(Start looping) 

(Move in a blank) 
(decrement pointer) 

(Go until count < 0) 

(Do a normal re-entry) 


(Decrement 16 bit value) 
(Get the low byte) 

(If a borrow will occur,) 
(then borrow from high...) 

(Decrement low) 

(Re-enter FORTH) 


Listing 3 


C; 

Listing 4 


DUP 

(Duplicate TOS) 

0 ,X LDA, 

(Get low byte) 

PHA, 

(Set up for PUSH) 

1 ,X LDA, 

(Put high in Accumulator) 

PUSH JMP, 

(Push 16 bit value) 


C; 


SWAP 

(Exchange top stack items) 

2 ,X LDA, 

(Get low byte of 20S) 

PHA, 

(Save it) 

0 ,X LDA, 

(Put low byte of TOS) 

2 ,X STA, 

( into low byte of 20S 

3 ,X LDA, 

(Save high byte of 20S) 

1 ,X LDY, 

(Put high byte of TOS) 

3 ,X STY, 

( into high byte of 20S) 

PUT JMP, 

(Put old 20S into TOS) 
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Listing 5 


HEX 

CODE ?TERMINAL 
DOIF LDA, 

# 7 EOR, 

NE IF, 

INY, 

ENDIF, 

TYA 

PUSHOA JMP, 
C; DECIMAL 


(Any console key pressed?) 
(Load status byte) 

(Any low bits reset? 

(If so,) 

(then leave a true value) 

(Put true or false into A) 
(Push to parameter stack) 


Listing 6 


CODE 

C@ 

(Byte 

fetch routine) 


0 X) LDA, 

(Load 

from address on 

C; 

PUTOA JMP, 

(Push 

byte value) 


TOS) 


Listing 7 


CODE XOR 

0 ,X LDA, 

2 ,X EOR, 
PHA, 

1 ,X LDA, 

3 ,X EOR, 
BINARY JMP, 

C; 


(One example of XOR) 

(Get low byte of TOS) 
(Exclusive or it with 20S) 
(Push low result) 

(Get high byte of TOS) 

(XOR it with high of 20S) 
(Drop TOS and replace 20S) 


Listing 8 


CODE XOR 

0 ,X LDA, 

2 ,X EOR, 

2 ,X STA, 

1 ,X LDA, 

3 ,X EOR, 

3 ,X STA, 
POP JMP, 

C; 

Listing 9 

CODE C! 

2 ,X LDA, 

0 )X STA, 
POPTWO JMP, 

C; 


(Another exclusive or) 
(Get low byte of TOS) 
(XOR with low of 20S) 
(Put in low of 20S) 
(Get high byte of TOS) 
(XOR with high of 20S) 
(Put in high of 20S) 
(Drop TOS) 


(Byte store routine) 
(Pick up byte to store) 
(Indirectly store it) 
(Drop address and byte) 
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Listing 10 

CODE >R 

1 ,X LDA, 
PHA, 

0 ,X LDA, 
PHA, 

POP JMP, 


(Transfer TOS to R-stack) 
(Pick up high of TOS) 

(Put on R-stack) 

(Pick up low of TOS) 

(Put on R-stack) 

(Lose top stack item) 


Listing 11 


HEX 

CODE K 

XSAVE STX, 
TSX 

109*,X LDA, 
PHA, 

10A ,X LDA 
XSAVE LDX, 
PUSH JMP, 

C; DECIMAL 


(3rd inner DO loop index) 
(Save P-stack pointer) 

(Pick up R-stack pointer) 
(Pick up low byte of value) 
(Save it) 

(Put high byte of value in A) 
(Restore P-stack pointer) 
(Push 16 bit index value) 
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Appendix B 


Quick Reference Chart 


valFORTH 6502 Assembly Words 

ASSEMBLER ( ) 

Calls up the assembler vocabulary for subsequent assembly language 
programming. 

CODE cccc { — ) 

Enters the new word "cccc" into the dictionary as machine language 
word and calls up the assembler vocabulary for subsequent assembly language 
programming. CODE also sets the system up for security checking. 


C; { — } 

Terminates an assembly language definition by performing a security 
check and setting the CONTEXT vocabulary to the same as the CURRENT 
vocabulary. 

END-CODE ( — ) 

A commonly used synonym for the word C; above. The word C; is 
recommended over END-CODE. 

SUBROUTINE cccc ( —- ) 

Enters the new word "cccc" into the dictionary as machine language 
subroutine and calls up the assembler vocabulary for subsequent assembly 
language programming. SUBROUTINE also sets the system up for security 
checking. 


;C0DE ( — ) 

When the assembler is loaded, puts the system into the assembler 
vocabulary for subsequent assembly language programming. See main 
glossary for further explanation. 


Control Structures 


IF, ( flag —- addr 2 ) 

Begins a machine language control structure based on the 6502 status 
flag on top of the stack. Leaves an address and a security check value 
for the ELSE, or ENDIF, clauses below, "flag" can be EQ , NE , CC , CS , 
VC , VS , MI , or PL . Command forms: 

... flag..IF,..if-true..ENDIF,.. .all... 

...flag..IF,..if-true..ELSE,..if-false..ENDIF,..all... 
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ELSE, ( addr 2 — addr 3 ) 

Used in an IF, clause to allow for execution of code only if IF, 
clause is false. If the IF, clause is true, this code is bypassed. 

See IF, above for command form. 


ENDIF, ( addr 2/3 — ) 

Used to terminate an IF, control structure clause. Additionally, 
ENDIF, resolves all forward references. See IF, above for command form. 

BEGIN, ( — addr 1 ) 

Begins machine language control structures of the following forms: 

...BEGIN,...AGAIN,... 

...BEGIN,...flag..UNTIL,... 

...BEGIN,...flag..WHILE,..while-true..REPEAT,... 

where "flag" is one of the 6502 statuses: EQ , NE , CC , CS , VC , 

VS , MI , and PL . See the very similar BEGIN in the main glossary for 
additional information. 


UNTIL, ( addr 1 flag — ) 

Used to terminate a post-testing BEGIN, clause thus allowing for 
conditional looping of a program segment while "flag" is false. See 
BEGIN, above for more information. 


WHILE, ( addr 1 flag — addr 4 ) 

Used to begin a pre-testing BEGIN, clause thus allowing for 
conditional looping of a program segment while"flag" is true. See BEGIN, 
above for command format. 

REPEAT, ( addr 4 — ) 

Used to terminate a pre-testing BEGIN,..WHILE, clause. Additionally, 
REPEAT, resolves all forward addresses of the current WHILE, clause. 

See BEGIN, above. 


AGAIN, ( addr 1 — ) 

Used to terminate an unconditional BEGIN, clause. Execution cannot 
exit this loop unless a JMP, instruction is used. See BEGIN, clause for 
more information. 
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Parameter Passing 


NEXT ( — addr ) 

Transfers control to the next FORTH word to be executed. The 
parameter stack is left unchanged. 

PUSH ( addr ) 

Pushes a 16 bit value to the parameter stack whose low byte is 
found on the 6502 return stack and whose high byte is found in the 
accumulator. 

PUSHOA ( - addr ) 

Pushes a 16 bit value to the parameter stack whose low byte is 
found in the accumulator and whose high byte is zero. 

PUT ( — adidr ) 

Replaces the value currently on top of the parameter stack with the 
16 bit value whose low byte is found on the 6502 stack and whose high 
byte is in the accumulator. 


PUTOA ( — addr ) 

Replaces the value currently on top of the parameter stack with the 
16 bit value whose low byte is in the accumulator and whose high byte 
is set to zero. 

BINARY ( — addr ) 

Drops the top value of the parameter stack and then performs a PUT 
operation described above. 

POP and P0PTW0 ( — addr ) 

POP drops one value from the parameter stack. P0PTW0 drops two 
values from the parameter stack. 


SETUP 


( — addr ) 


Moves one to four values to the N scratch area in the zero page and 
drops all values moved from the parameter stack. 

N ( — addr ) 

Points to a nine-byte scratch area in the zero page beginning at 
N-l and going to N+7. Typically used by words which use indirect-indexed 
addressing where addresses must be stored in the zero page. See SETUP 
above. 
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Opcodes ( 


ADC, 

AND, 

ASL, 

BIT, 

BRK, 

CLC, 

CLD, 

CL I 

CLV, 

CMP, 

CPX, 

CPY, 

DEC, 

DEX, 

DEY, 

EOR 

INC, 

INX, 

INY, 

JSR, 

JMP, 

LDA, 

LDX, 

LDY 

LSR, 

NOP, 

ORA, 

PHA, 

PHP, 

PLA, 

PLP, 

ROL 

ROR, 

RTI, 

RTS, 

SBC, 

SEC, 

SED, 

SEI, 

STA 

STX, 

TAX, 

TAY, 

TSX, 

TXA, 

TXS, 

TYA, 



Aliases 

NXT, = NEXT JMP, 
PSH, = PUSH JMP, 
PUT, = PUT JMP, 
PSHA, = PUSHOA JMP, 
PUTA, = PUTOA JMP, 
POP, = POP JMP, 
POP2, = POPTWO JMP, 
XL, = XSAVE LDX, 
XS, = XSAVE STX, 
THEN, = ENDIF, 

END, = UNTIL, 



VI-24 



VII. valFORTH 1.1 SUPPLIED SOURCE LISTING 


Screen s 30 

0 < Outo command ) 

1 

£ BASE @ HEX 

3 

4 : ZAP < addr # — ) 

5 -DUP 

6 IF O+S 

7 DO D£0A C@ 7F AND I C! 

B LOOP 

9 ELSE DROP 

10 ENDIF ; 

11 

12 : -WAIT ( — ) 

13 BEGIN 7TERMINAL NOT UNTIL ; 

14 

15 DCX ==> 


Screen; 33 

0 ( Auto command ) 

1 

£ : QUEST£ ( — r . ) 

3 ." Format and save: " 

4 ." press OPTION" CR 

5 . " Just save: " 

6 . " press SELECT" CR CR 

7 WAIT ?TERMINAL -WAIT 

8 . " Prepare disk — " 

9 ." press START" 

10 WAIT -WAIT ; 

11 : CSV ( — > 

1£ . " Prepare cassette " 

13 ." (play/record) — " CR 

14 . " press START" CR 

15 WAIT CSAVE -WAIT ; —> 



Screen: 31 

Screen: 34 

0 ( 

1 

Auto command ) 

0 ( 

1 

Auto command 

1 

£ : 

BEHEAD ( — ) 

1 

d ! 

DSV 

3 

0 > R CR . " Now protecting..." 

3 

QUESTS 

4 

CR VOC-LINK i? 

4 

4 = 

5 

BEGIN 

5 

IF 

6 

DUP £- (? 

6 

1 (FMT) 1 <> 

7 

BEGIN 

7 

IF 

8 

DUP 1+ OVER R> 1+ >R 

8 

CR ." Format error 

9 

R 15 MOD NOT IF . " . " ENDIF 

9 

ELSE 

10 

R 495 MOD NOT IF CR ENDIF 

10 

DODISK 

11 

C@ 63 AND WIDTH @ MIN 1- 

11 

END IF 

1£ 

ZAP PFA LFA <? DUP NOT 

1£ 

ELSE 

13 

UNTIL 

13 

DODISK 

14 

DROP 9 DUP NOT 

14 

ENDIF CR ; 

15 

UNTIL R> £DROP ; —> 

15 



Screen: 3£ 

0 < Auto command ) 

1 

£ : QUEST ( — ) 

3 CR 

4 . " Save on disk: " 

5 . " press OPTION" CR 

6 . " Save on cassette: " 

7 . " press SELECT" CR 

8 ." Exit: 

9 . " press START" CR CR ; 

10 

11 : DODISK <— ) 

12 (SAVE) ’ SAVE 3£ + C-EX 

13 741 <? 1£8 - 1 1 R/W ; 

14 

15 ==> 


Screen: 35 

0 ( Auto command ) 

1 

£ : DECIS ( — ) 

3 BEGIN 

4 QUEST WAIT 7TERMINAL -WAIT 

5 DUP 1 = 

6 IF DROP 1 

7 ELSE 

8 £ = 

9 IF 

10 CSV 

11 ELSE 

1£ DSV 

13 ENDIF 0 

14 ENDIF 

15 UNTIL ; —> 






Screen: 36 Screen: 39 


0 

1 

( Auto command 

) 

0 

< Text output: 

BEEP ASCII 

) 

X 

£ 

: AUTO 

( — ) 

1 

£ 

: BEEP 

( 

__ __ 'j 

3 

CC0MPILE3 ’ CR 


3 

0C0 0 



4 

." Auto? Y/N " KEY 89 = 

CR 

4 

DO 



5 

IF 


5 

08 0D01F C! 

6 0 DO LOOP 


6 

CFA » ABORT 6 + ! 


6 

00 0D01F C! 

6 0 DO LOOP 


7 

’ COLD CFA ’ ABORT 8 + 

! 

7 

LOOP ; 



8 

-1 £6 +ORIGIN ! 


8 




9 

’ ZAP NFA DP ! 


9 

: ASCII 

( ccc, — 

<b>) 

10 

BEHEAD DECIS ABORT 


10 

BL WORD 



11 

ELSE 


11 

HERE 1+ C@ 



1£ 

DROP ." Auto aborted... 

" CR 

1£ 

STATE @ 



13 

ENDIF ; BASE 

i 

13 

IF 



14 



14 

COMPILE CLIT 

' c. 


15 



15 

ENDIF ; IMMEDIATE 

—> 


Screen: 37 Screen: 40 


0 

0 

< Text output: EJECT 

LISTS 

) 

1 

£ 

1 

o 

DCX 



3 

iT. 

3 

: EJECT 

( - 

— ) 

4 

4 

1£ EMIT ; 



5 

5 




6 

6 

: LISTS 

( s # - 

— ) 

7 

7 

0 <ROT 0+S 



8 

8 

DO 



9 

9 

CR I LIST 



10 

10 

1+ DUP 3 MOD 0= 



11 

11 

IF EJECT ENDIF 



1£ 

i£ 

?EXIT 



13 

13 

LOOP 



14 

14 

DROP ; 



15 

15 



==> 


Screen: 38 

0 ( Text output: S: P: ) 

1 

£ BASE e HEX 

Lj 

A • S s ( f 7 —— ) 

5 PFLAG @ SWAP 

6 IF 1 DR ELSE FE AND ENDIF 

7 PFLAG ! ; 

8 

9 : P: ( f — ) 

10 PFLAG @ SWAP 

11 IF £ DR ELSE FD AND ENDIF 

1£ PFLAG ! ; 

13 

14 

15 ==> 


Screen: 41 

0 ( Text output: PLISTS PLIST ) 
1 

£ : PLISTS ( s # — ) 

3 PFLAG @ <ROT 

4 ON P: 

5 LISTS 

6 CR PFLAG ! ; 

7 

8 : PLIST ( s -- ) 

9 1 PLISTS ; 

10 
11 
12 

13 

14 

15 


BASE ! 



Screen: 42 


Screen: 45 



0 

( Debug: B? [FREED 

FREE ) 

0 

( 

Debug: CDUMP 


) 

1 

BASE 0 DCX 


1 





2 

MS: )( 19 KLOAD ) 


2 

( 

Character dump routine 

) 

3 

HEX 


3 





4 



4 

■ 

a 

CDUMP 

( a # 

— ) 

5 

: B? 

( — ) 

5 


PFLAG 0 (ROT OFF 

P: 


& 

BASE 0 DUP ( 

Display ) 

& 


OVER + SWAP 



7 

DECIMAL . < 

current ) 

7 


DO 



8 

BASE ! ; ( 

radix ) 

a 


CR I 5 U. R 



9 



9 


SPACE I DUP 10 

+ SWAP 


10 

: (FREE) 

( — r. ) 

10 


DO 



11 

2E5 0 PAD - ; 


11 


I C® SPEMIT 



12 



12 


LOOP 



13 

: FREE 

( — ) 

13 


?EX IT 



14 

(FREE) U. . " bytes" 

CR 5 

14 


10 /LOOP 



15 


==> 

15 


CR PFLAG ! ; 


--> 


Screen: 43 



Screen: 46 


0 

1 

( Debug: H. CFALIT 

) 

0 

1 

( Stack print: DEPTH 

) 

I 

o 

: CFALIT ( 

ccc, — (b> ) 

X 

2 

: DEPTH ( 

n — ) 

3 

STATE 0 



3 

S0 0 SP0 - 2/ 1 - ; 


4 

[COMPILED [ 



4 



5 

[COMPILED ’ CFA 



5 

CFALIT . VARIABLE X.S 


6 

SWAP IF [COMPILED 

D 

END IF 

6 



7 

[COMPILED LITERAL 

• 

i 


7 

: XDOTS 

( — ) 

8 

IMMEDIATE 



8 

DEPTH 


9 




9 

IF 


10 

’ ( H. —> ) ( ) 



10 

SP@ 2- S0 0 2- 


11 

: H. 


( b — ) 

11 

DO I 0 X.S 0 EXECUTE 


12 

BASE 0 HEX 

( 

Display ) 

12 

-2 +LOQP 


13 

SWAP 0 

( 

# in hex ) 

13 

ELSE 


14 

<####> TYPE 



14 

." Stack empty " 


15 

BASE ! ; 


—> 

15 

ENDIF ; 

==> 


Screen: 44 


Screen: 47 

0 

( 

Debug: #DUMP 

) 

0 

( 

Stack print: .S U.S STACK ) 

1 




1 



2 

( 

memory dump ) 


2 

a 

a 

.S CFALIT . X.S ! XDOTS ; 

3 




3 

a 

a 

U.S CFALIT U. X.S ! XDOTS ; 

4 

■ 

a 

#DUMP 

< a # — ) 

4 



5 


0+S 


5 

a 

a 

STKPRT 

6 


DO 


& 


CR ." ( " XDOTS ." ) " ; 

7 


CR I 5 U. R I 


7 



8 


DUP 8 + SWAP 


8 

a 

a 

STACK ( f — ) 

9 


DO 


9 


IF 

10 


I C@ 4 .R 


10 


CFALIT STKPRT 

11 


LOOP 


11 


ELSE 

12 


?EX IT 


12 


CFALIT NOOP 

13 


8 /LOOP 


13 


END IF 

14 


CR ; 


14 


[ ’ PROMPT 11 + D 

15 



==> 

15 


LITERAL ! ; —> 



Screen : 48 

0 ( FORTH colon decompiler ) 

1 
2 

3 0 VARIABLE .WORD 

4 

5 : PWORD 

6 2+ NFA ID. 5 

7 

8 : 1BYTE 

9 PWORD .WORD 0 C@ . 

10 1 .WORD +! ■ 

11 

12 : 1WORD 

13 PWORD .WORD @ @ . 

14 2 .WORD +! ; 

15 ==> 


Screen: 49 

0 ( FORTH colon decompiler ) 

1 : NP ( n — n ) 

2 DUP CFALIT ;S = OVER 

3 CFALIT <;CODE) = OR 

4 IF PWORD CR CR PROMPT QUIT 

5 ENDIF 7TERMINAL 

6 IF DROP PROMPT QUIT ENDIF ; 

7 

8 : BRNCH 

9 PWORD . " to " .WORD 0 .WORD 0 

10 0 + U. 2 .WORD + ! ; 

11 

12 : NXT1 

13 .WORD 0 U. 2 SPACES 

14 .WORD 002 .WORD + ! • 

15 — > 


Screen: 50 

0 ( FORTH colon decompiler ) 

1 

2 : STG 

3 PWORD 22 EMIT .WORD 0 

4 DUP COUNT TYPE 22 EMIT 

5 C@ .WORD 0+1+ .WORD ! ; 

6 


7 : 

8 

CKIT 

DUP 

CFALIT 

0BRANCH 


9 

OVER 

CFALIT 

BRANCH 

* OR 

10 

OVER 

CFALIT 

(LOOP) 

= OR 

11 

OVER 

CFALIT 

(+LOOP) 

= OR 

12 

OVER 

CFALIT 

(/LOOP) 

= OR 

12 

13 

14 

IF BRNCH 

ELSE DUP CFALIT LIT 


15 

IF 

1WORD 




Screen: 51 

0 ( FORTH colon decompiler ) 


1 

2 

ELSE 

Jj 

DUP CFALIT CLIT = 

4 

IF 1BYTE 

5 

ELSE 

6 

DUP CFALIT COMPILE = 

7 

IF PWORD CR NXT1 PWORD 

8 

ELSE 

9 

DUP 4-0 A922 = 

10 

IF STG 

11 

ELSE PWORD ENDIF 

12 

END IF 

13 

END IF 

14 

END IF 

15 

ENDIF ; —> 


Screen: 52 

0 ( FORTH colon decompiler ) 

1 

2 : 7DOCOL 

3 DUP 2- 0 

4 C ’ : 12 + 1 LITERAL - 

5 IF . " Primitive pfa dump:" 

6 2- 0 18 #DUMP 

7 PROMPT QUIT 

8 ENDIF ; 

9 
10 
11 
12 

13 

14 

15 ==> 


Screen: 53 

0 ( FORTH colon decompiler ) 

1 

2 : DCMPR ( 

3 DUP NFA CR CR DUP ID. 

4 C0 40 AND 

5 IF ." (IMMEDIATE)" 

6 END IF 

7 CR CR 7DOCOL .WORD ! 

8 BEGIN NXT1 NP CKIT CR 

9 

10 : DECOMP 

11 CCOMPILE] ’ DCMPR ; 

12 

13 

14 

15 BASE ! ;S 


PFA — ) 


AGAIN ; 



) 


Screen: 54 

0 

1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 


Screen s 57 

0 ( fig editor: MARK 
1 

2 : MARK 

3 10 0 

4 DO 

5 I LINE UPDATE 

6 DROP 

7 LOOP ; 

8 
9 

10 
11 
12 

13 

14 

15 — > 


Screen: 55 

0 
1 
2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 


Screen: 58 

0 ( fig editor: WHERE ) 

1 

2 VOCABULARY EDITOR IMMEDIATE 

3 

4 ( Note: the fig bug is fixed > 

5 < in WHERE below. ) 

8 

7 : WHERE < n n — ) 

8 2DUP DUP B/SCR / DUP SCR ! 

9 ." Scr # " DECIMAL . SWAP 

10 C/L /MOD C/L * ROT BLOCK + 

11 CR C/L -TRAILING TYPE 

12 CR HERE Cl? - 2- 0 MAX SPACES 

13 1 2FE C! 1C EMIT 0 2FE C! 

14 [COMPILE] EDITOR QUIT ; 

15 ==> 


Screen: 56 

0 < fig editor: TEXT LINE ) 

1 

2 BASE @ HEX 

3 

4 ( This editor is based on the ) 

5 ( example editor supplied in ) 

6 (the "fig-FORTH Installation ) 

7 ( Manual." ) 


8 

9 : TEXT 

10 HERE C/L 1 + BLANKS WORD 

11 HERE PAD C/L 1+ CMOVE ; 

12 

13 : LINE 

14 DUP FFF0 AND 17 7ERROR 

15 SCR @ (LINE) DROP 


Screen: 59 

0 ( fig editor: #L’s -MOVE ) 

1 

2 EDITOR DEFINITIONS 

4 : #LOCATE ( — n n > 

5 R# i? C/L /MOD ; 

6 

7 : #LEAD ( — n n ) 

8 #LOCATE LINE SWAP ; 

9 

10 : #LAG ( — n n ) 

11 #LEAD DUP > R + C/L R> - ; 

12 

13 : —MOVE ( n n — ) 

14 LINE C/L CMOVE UPDATE ; 





s 


> 


I TOP 


) 


Screen: 60 

0 ( fig editor: H E 
1 

£ : H < n — ) 

3 LINE PAD 1+ C/L 

4 DUP PAD C! CMOVE ; 

5 

6 : E < n — ) 

7 LINE C/L BLANKS UPDATE ; 

8 

9 : S < n — ) 

10 DUP 1- 0E 

11 DO 

12 I LINE 

13 I 1+ -MOVE 

14 -1 +LOOP 

15 E ==> 


Screen: 63 

0 ( fig editor: 
1 


£ : I 

( n — ) 

3 DUP S R ; 


4 


5 : TOP 

( — ) 

6 0 R# ! ; 



7 

8 
9 

10 

11 

12 

13 

14 


Screen: 61 

Screen: 64 



0 < 

fig editor: D M ) 

0 ( 

fig editor: CLEAR 

COPY 

> 

1 


1 




2 : 

D ( n — ) 

■ 2 : 

CLEAR 

( r. 

— ) 

3 

DUP H 0F DUP ROT 

3 

SCR ! 10 0 



4 

DO 

4 

DO 



5 

I 1+ LINE 

5 

FORTH I EDITOR E 



6 

I -MOVE 

6 

LOOP ; 



7 

LOOP 

7 




8 

e ; 

8 : 

COPY 

< n n 

— ) 

9 


9 

B/SCR * OFFSET 0 + 

SWAP 


10 : 

M < n — ) 

10 

B/SCR * B/SCR OVER 

+ SWAP 


11 

R# +! CR SPACE 

11 

DO 



12 

#LEAD TYPE 14 EMIT #LAG 

12 

DUP FORTH I BLOCK 


13 

TYPE #LOCATE . DROP ; 

13 

2- ! 1+ UPDATE 



14 


14 

LOOP 



15 

—> 

15 

DROP ; 


==> 


Screen: 62 



Screen: 65 



0 

( 

fig editor: T L R 

P 

) 

0 ( 

fig editor: 

1LINE FIND 

) 

1 





1 




2 

m 

T 

< 

r. — ) 

2 : 

1LINE 

( — f 

) 

3 


DUP C/L * R# ! 



3 

#LAG PAD COUNT 


4 


DUP H 0 M ; 



4 

MATCH R# +! 

* 

i 


5 





5 




6 

■ 

m 

L 


< — ) 

6 : 

FIND 

( — 

) 

7 


SCR 0 LIST 0 M ; 



7 

BEGIN 



8 





8 

3FF R# @ < 



9 

* 

m 

R 

( 

n — ) 

9 

IF 



10 


PAD 1+ SWAP -MOVE ; 



10 

TOP PAD 

HERE C/L 


11 





11 

1+ CMOVE 

0 ERROR 


12 

m 

P 

< 

n — ) 

12 

END IF 



13 


1 TEXT R ; 



13 

1LINE 



14 





14 

UNTIL ; 



15 




==> 

15 


— 

-> 



Screen: 66 



Screen: i 

69 

0 ( 

fig editor: 

DELETE ) 

0 

( End 

of fig-FORTH ed 

1 




1 



£ : 

DELETE 


< n — ) 

£ 

FORTH 

DEFINITIONS DCX 

& 

> R #LAG + FORTH 

R - 

3 



4 

#LAG R MINUS 

R# 

+! #LEAD 

4 



5 

+ SWAP CMOVE 

R> 

BLANKS 

5 



6 

UPDATE ; 



6 



7 




7 



a 




8 



9 




9 



10 




10 



11 




11 



IS 




1 £ 



13 




13 



14 




14 



15 



==> 

15 




Screen: 67 


Screen: 70 

0 

( 

fig editor: N F B 

X ) 

0 

1 




1 

£ 

■ 

N 

( — ) 

£ 

3 


FIND 0 M ; 


3 

4 




4 

5 

■ 

■ 

F 

( — ) 

5 

6 


1 TEXT N ; 


6 

7 




7 

8 

m 

m 

B 

( — ) 

8 

9 


PAD C@ MINUS M ; 


9 

10 




10 

11 

m 

m 

X 

( — ) 

11 

12 


1 TEXT FIND 


1 £ 

13 


PAD C@ DELETE 


13 

14 


0 M ; 


14 

15 



—> 

15 


Screen: 68 


Screen: 71 

0 ( 

fig editor: TILL 

C ) 

0 

1 



1 

£ : 

TILL 

( — ) 

£ 

3 

#LEAD + 1 TEXT 


3 

4 

1LINE 0= 0 7ERR0R 


4 

5 

#LEAD + SWAP - 


5 

6 

DELETE 0 M ; 


6 

7 



7 

8 : 

C 


8 

9 

1 TEXT PAD COUNT #LAG ROT 

9 

10 

OVER MIN > R FORTH 

R R# +! 

10 

11 

R - >R DUP HERE R 

CMOVE 

11 

1 £ 

HERE #LEAD + R> CMOVE R> 

1 £ 

13 

CMOVE UPDATE 0 M ; 


13 

14 



14 

15 


==> 

15 



75 


Screen: 72 

0 ( Disk copy routines ) 

1 BASE 0 DCX 

2 

3 0 VARIABLE SEC/PAS 

4 0 VARIABLE SECNT 

5 

6 : AXLN ( system ) 

7 4 PICK 0 

B DO 3 PICK I 128 * + 

9 3 PICK I + 3 PICK R/W 

10 LOOP 2DR0P 2DR0P ; 

11 

12 : DCSTP 

13 741 0 PAD DUP 1 AND - 

14 0 128 U/ SWAP DROP 

15 SEC/PAS ! 0 SECNT ! ; ==> 


Screen: 73 

0 < Disk copy routines ) 

1 

2 : DISKC0PY1 < — > 

3 DCSTP 

4 BEGIN 

5 CR CR . " Insert source and pu 

6 sh START" WAIT 

7 720 SECNT @ - SEC/PAS 0 MIN 

8 DUP > R PAD DUP 1 AND - SECNT 

9 0 2DUP 5 PICK <ROT 1 AXLN 

10 CR CR . " Insert dest. and pu 

11 sh START" WAIT 0 AXLN CR 

12 R> SECNT +! SECNT 0 DUP . 

13 . " sectors copied" 720 = 

14 UNTIL EMPTY-BUFFERS 

15 CR . " Done" CR ; —> 


Screen: 

0 

1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 


Screen: 76 

0 ( 6502 Assembler in FORTH ) 

1 ( 

2 ( Originally written by 

3 ( Patrick Mullarky. 

4 < 

5 ( Modified extensively 2/82 

6 ( by Stephen Maguire, 

7 ( Valpar International 

8 ( 

9 ( 

10 < This assembler conforms to the 

11 ( fig "INSTALLATION GUIDE" and 

12 ( to APX versions of FORTH. 

13 < 

14 ( ) 

15 ==> 


Screen: 74 


Screen: 77 


0 

( 

Disk copy routines 


) 

0 

( 

1 





1 

( 

2 

» 

■ 

DISKC0PY2 

< — 

) 

2 

( 

3 


DCSTP 



3 

( 

4 


CR ." Insert source in 

drive 

1 

4 

< 

5 

II 

CR ." Insert dest. in 

drive 

2 

5 

< 

6 

II 

CR ." Press START to copy" 


6 

< 

7 


WAIT 



7 

( 

8 


BEGIN 



8 

( 

9 


720 SECNT 0 - SEC/PAS 

0 MIN 


9 

( 

10 


DUP > R PAD DUP 1 AND - 

- SECNT 

10 

< 

11 


0 2DUP 5 PICK <ROT 



11 

( 

12 


1 AXLN 720 + 0 AXLN 



12 

( 


13 R> SECNT +! SECNT 0 720 = 

14 UNTIL EMPTY-BUFFERS 

15 CR ." Done" CR ; BASE ! 


13 ( 

14 < 

15 


6502 Assembler in FORTH 

Now supports: 

IF,...ELSE,...ENDIF, 
BEGIN,...WHILE,...REPEAT, 
BEGIN, . . .AGAIN, 

BEGIN,...any flag UNTIL, 

C; & END-CODE 

;CODE 

Also supports: 

compiler security 
definition checking 


) 



? 



Screen: 78 Screen: 81 


0 

< 8502 Assembler in 

FORTH ) 

0 

< 6502 Assembler in FORTH ) 

1 

’ < TRANSIENT 

TRANSIENT 

) ( ) 

1 


2 

BASE @ HEX 




2 

: ENDIF, 


ASSEMBLER DEFINITIONS 


3 

DUP 2 = IF 

4 





4 

DROP DUP HERE SWAP - 

5 

: SB 




5 

DUP 7F > 5 7ERROR 

6 

<BUILDS C, 

DOES) @ C, 

■ 

9 

6 

DUP -80 < 5 7ERROR 

7 





7 

SWAP 1- C! 

8 

000 SB BRK, 

018 

SB 

CLC, 

8 

ELSE 

9 

0D8 SB CLD, 

058 

SB 

CLI, 

9 

3 ?PAIRS HERE SWAP ! 

10 

0B8 SB CLV, 

0CA 

SB 

DEX, 

10 

ENDIF ; IMMEDIATE 

11 

088 SB DEY, 

0E8 

SB 

INX, 

11 


12 

0C8 SB INY, 

0EA 

SB 

NOP, 

12 

: ELSE, 

13 

048 SB PHA, 

008 

SB 

PHP, 

13 

DUP 2 ?PAIRS 4C C, HERE 0 , 

14 

068 SB PLA, 

028 

SB 

PLP, 

14 

<ROT [COMPILE! ENDIF, 3 ; 

15 

040 SB RTI, 

060 

SB 

RTS, ==> 

15 

—> 


Screen; 79 


Screen: 82 


0 

( 6502 Assembler in FORTH ) 

0 

< 

6502 Assembler in 

FORTH ) 

1 

038 SB SEC, 

0F8 SB SED, 

1 




CL 

078 SB SEI, 

0AA SB TAX, 

2 

• 

■ 

THEN, 


3 

0BA SB TSX, 

08A SB TXA, 

3 


[COMPILE! ENDIF, ; 

IMMEDIATE 

4 

09A SB TXS, 

098 SB TYA, 

4 




5 

0A8 SB TAY, 


5 

■ 

m 

BEGIN, 


6 



6 


HERE 1 ; 

IMMEDIATE 

7 

0 VARIABLE >J 

: ) 1 ) J ! ; 

7 




a 



8 

• 

■ 

UNTIL, 


9 

: 3BY 


9 


SWAP 1 7PAIRS C, 


10 

<BUILDS C, 

DOES) C@ DUP 4C = 

10 


HERE 1+ - DUP -80 


11 

IF >J & IF 

DROP 6 C ENDIF 

11 


< 5 7ERROR C, ; 

IMMEDIATE 

12 

ENDIF C, , 

0 )J ! ; 

12 




13 



13 

■ 

m 

END, 


14 

04C 3BY JMP, 

06C 3BY JMP(), 

14 


[COMPILE! UNTIL, ; 

IMMEDIATE 

15 
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10 <BUILDS 

11 HERE F! 6 ALLOT 
IS DOES) F@ ; 

13 

14 


Screen: 135 
0 
1 
£ 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 


Screen: 133 
0 ( Floating 
1 
£ 

3 

4 

5 

6 

7 

8 
9 

10 
11 
12 

13 

14 

15 


F0= F= F < F> 


Screen: 136 

0 ( Screen code conversion words ) 
1 


• 

• 

F0= 

( 

fp — 

f ) 

£ 

BASE 0 HEX 







OR OR 0= ; 




•—i 












4 

CODE > BSCD 




( a a 

n — 

m 

m 

F= 

< fp 

fp — 

f ) 

5 

A9 C, 03 

c, 

£0 

c, 

SETUP 



F- F0= ; 




6 

HERE C4 

c, 

C£ 

c, 

D0 C, 

07 C 


F < 




7 

C6 C, C3 

c, 

10 

c, 

03 C, 

4C C 

a 

• 

< fP 

fp — 

f ) 

8 

NEXT , 


B1 

C, 

C6 C, 

48 C 


F- DROP DROP 80 

AND 0) ; 


9 

29 C 7F 

C, 

C9 

c, 

60 C, 

B0 C, 


F> 




10 

0D c’ C9 

C, 

£0 

c, 

B0 C, 

06 C, 

■ 

» 

< fp 

fp — 

f ) 

11 

18 C, 69 

c, 

40 

c, 

4C C, 

HERE 


FSWAP F < ; 




12 

£ ALLOT 38 

C, 

E9 

C, 

£0 C, 

HERE 






13 

SWAP ! 91 

C, 

C4 

C, 

68 C, 

£9 C, 


BASE 


14 

15 




Screen: 
0 
1 


134 


6 

7 

a 

9 

10 

li 

1£ 

13 

14 

15 


Screen: 137 
0 < Screen 
1 


code conversion words ) 


£ 

80 C, 

11 

c, 

C4 

c, 

91 

c, 

C4 C, 

3 

C8 C, 

D0 

c, 

D3 

c, 

E6 

c, 

C7 C, 

4 

E6 C, 

C5 

c, 

4C 

C, 



C; 

6 

CODE BSCD) 




( a a 

n — 

7 

A9 C, 

03 

c, 

£0 

C, 

SETUP 


8 

HERE 

C4 

c, 

C£ 

C, 

D0 

c, 

07 C, 

9 

C6 C, 

C3 

c, 

10 

C, 

03 

c, 

4C C, 

10 

NEXT , 



B1 

C, 

C6 

c, 

48 C, 

11 

£9 C, 

7F 

c, 

C9 

C, 

60 

c, 

B0 C, 

12 

0D C, 

C 9 

c, 

40 

C, 

B0 

c, 

06 C, 

13 

18 C, 

69 

c, 

£0 

C, 

4C 

c, 

HERE 

14 

£ ALLOT 

38 

C, 

E9 

C, 

40 

c, 

HERE 

15 










> 



VI.0 ) 


Screen: i38 

0 ( Screen code conversion words ) 
1 


Screen: 141 

0 ( ValFORTH Video editor 
1 


£ 

SWAP 

» 

91 

c, 

C4 

c, 

68 

c. 

29 

c, 

£ 

3 

80 

C, 

11 

C, 

C4 

C, 

91 

c, 

C4 

C, 

3 

4 

ca 

C, 

D0 

C, 

D3 

C, 

E6 

C, 

C7 

C, 

4 

5 

E6 

C, 

C5 

C, 

4C 

C, 

i 




5 


6 

7 

8 
9 

10 

11 

12 

13 

14 


> SCD SP0 DUP 1 > BSCD 
SCD> SP0 DUP 1 BSCD> 


6 

7 

8 
9 

10 

11 

12 

13 

14 


15 


BASE ! 


15 


LMOVE 32 CMOVE ; 

BOL 88 0 YLOC 0 1+ 32 * + 


SBL 88 0 544 + 
CURLOC 

BOL XLOC 0 + 
CSHQW 

CURLOC DUP 
C@ 128 OR 
SWAP C! ; 


( -> 

( SCR ADDR ) 

(-) 

( GET SCR ADDR ) 
( INVERSE CHAR ) 
< STORE ON SCR ) 
—> 


Screen: 139 
0 
1 


4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 


Screen: 142 

0 ( ValFORTH Video editor VI.0 ) 
1 

2 : CBLftNK ( - ) 

3 CURLOC DUP C0 127 

4 AND SWAP C! ; 

5 

6 : UPCUR ( — ) 

7 CBLANK YLOC 0 1- DUP 

8 0< IF DROP 15 ENDIF 

9 YLOC ! CSHOW ; 

10 

11 : DNCUR ( — ) 

12 CBLANK YLOC 0 

13 1 + DUP 15 > 

14 IF DROP 0 ENDIF 

15 YLOC ! CSHOW ; ==> 


Screen: 140 

0 ( ValFORTH Video editor VI.0 ) 
1 

2 BASE 0 DCX ’ ( > SCD ) ( 68 KLOAD ) 

3 

4 VOCABULARY EDITOR IMMEDIATE 

5 EDITOR DEFINITIONS 

6 

7 0 VARIABLE XLOC ( X coord. ) 

8 0 VARIABLE YLOC < Y coord. ) 

9 0 VARIABLE LSTCHR ( last key ) 

10 0 VARIABLE ?ESC ( coded char?) 

11 0 VARIABLE TBLK ( top block ) 

12 0 VARIABLE UPSTAT 2 ALLOT ( rnap) 

13 

14 15 CONSTANT 15 32 CONSTANT 32 

15 128 CONSTANT 128 ==> 


Screen: 143 

0 ( ValFORTH Video editor VI.0 ) 
1 


4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 


LFCUR < — ) 
CBLANK XLOC 0 

1 - DUP 0 < (AT L-SIDE?) 
IF DROP 31 ENDIF ( FIX IF SO ) 
XLOC ! CSHOW ; 


RTCUR ( — ) 
CBLANK XLOC 0 

1+ DUP 31 > (AT R-SIDE?) 
IF DROP 0 ENDIF ( FIX IF SO ) 
XLOC ! CSHOW ; 


EDMRK 

1 YLOC 0 4 / UPSTAT + C! ; —> 



Screen: 144 

0 < ValFORTH Video editor VI.0 ) 
1 

2 : LNINS ( — ) 

3 CBLANK 

4 4 YLOC 04/ 

5 DO 1 I UPSTAT + C! LOOP 

6 YLOC 0 15 < 

7 IF 

B BOL DUP 32 + 

9 15 YLOC 0 - 32 * 

10 <CMOVE 

11 ENDIF 

12 BOL 32 ERASE 

13 CSHOW EDMRK ; 

14 

15 ==> 


Screens 147 

0 < ValFORTH Video editor VI.0 > 
1 

2 : SCRSV ( — ) 

3 88 0 32 + PAD 512 BSCD> 

4 4 0 

5 DO 

6 I UPSTAT + C0 

7 0 I UPSTAT + C! 

8 IF 

9 PAD 128 I * + 

10 TBLK 0 I + BLOCK 

11 128 CMOVE UPDATE 

12 ENDIF 

13 LOOP 

14 0 XLOC i 0 YLOC ! ; 


Screen: 145 

0 < ValFORTH Video editor VI.0 ) 
1 

2 : LNDEL < — ) 

3 CBLANK 

4 4 YLOC 04/ 

5 DO 1 I UPSTAT + C! LOOP 

6 YLOC © 15 < 

7 IF BOL < FROM ) 

8 DUP 32 + SWAP ( TO ) 

9 15 YLOC 0 - 32 * < # CH ) 

10 CMOVE 

11 ENDIF 

12 BOL 15 YLOC 0 - 

13 32 * + 32 ERASE 

14 CSHOW EDMRK ; 

15 —> 


Screens 148 

0 < ValFORTH Video editor VI.0 ) 
1 

2 : SCRGT ( — ) 

3 4 0 

4 DO 

5 TBLK 0 

6 I + BLOCK 

7 PAD 128 I * + 

8 128 CMOVE 

9 LOOP 

10 PAD 88 0 32 + 

11 512 > BSCD ; 

12 

13 

14 

15 ==> 


Screen: 146 

0 ( ValFORTH Video editor VI.0 ) 
1 

£ : RUB ( — ) 

3 XLOC 0 0= NOT ( ON L-EDGE? ) 

4 IF LFCUR 0 CURLOC C! 

5 CSHOW EDMRK 

6 ENDIF ; 

7 

8 : PTCHR ( — ) 

9 EDMRK 

10 LSTCHR 0 127 AND 

11 DUP LSTCHR ! 

12 > SCD CURLOC C! 

13 RTCUR XLOC 0 0= 

14 IF DNCUR ENDIF 

15 0 ?ESC ! CSHOW ; ==> 


Screen: 149 

0 ( ValFORTH Video editor VI.0 ) 
1 

£ : NWSCR < -1/0/1 — ) 

3 CBLANK DUP 

4 IF SCRSV ENDIF 2* 2* 

5 TBLK 0+0 MAX TBLK ! SCRGT 

6 TBLK 0 8 /MOD 

7 DUP <ROT SCR ! 

8 IF 44 ELSE 53 ENDIF 

9 ?1K NOT 

10 IF 

11 44 = SWAP 2* + DUP SCR ! 0 

12 ENDIF 

13 88 0 17 + C! 

14 0 84 C! 11 85 ! 1 752 C! 

15 .2 SPACES CSHOW ; —> 



Screen: 15® 

® < ValFORTH Video editor VI.® ) 
1 

£ : SPLCHR 1 ?ESC ! ; ( — ) 

wf 

4 : EXIT ( — ) 

5 CBLANK 19 LSTCHR ! 

6 ® XLOC ! ® YLOC ! ; 

7 

8 : EDTABT ( — ) 

9 UPSTAT 4 0 FILL 
1® EXIT ; 

11 
1 Im 

13 

14 

15 ==> 


Screen: 153 

0 < ValFORTH Video editor VI. 0 ) 
1 

£ : (V) < TBLK — ) 

3 DECIMAL 

4 DUP BLOCK DROP TBLK ! 

5 UPSTAT 4 0 FILL 

6 1 PFLAG i 0 GR. 

7 1 752 C! CLS 

0 1 559 C0 £52 

9 AND OR 559 C! 

10 112 560 0 6 + C! 

11 112 560 0 23 + C! 

12 Screen #” 11 SPACES 

13 ." ValFORTH" 

14 0 NWSCR 

15 —> 


Screen: 151 

0 < ValFORTH Video editor V1.0 ) 
1 


Screen: 154 

® ( ValFORTH Video editor 
1 


2 

: CONTROL 




3 

DUP 

19 

= 

IF 

DROP 

4 

DUP 

17 

= 

IF 

DROP 

5 

DUP 

£8 


IF 

DROP 

6 

DUP 

29 

= 

IF 

DROP 

7 

DUP 

30 


IF 

DROP 

8 

DUP 

31 

= 

IF 

DROP 

9 

DUP 

126 


IF 

DROP 

10 

DUP 

157 

= 

IF 

DROP 

11 

DUP 

156 

= 

IF 

DROP 

12 


£7 


IF 

DROP 


13 

14 

15 


( i 

n — ) 

2 

EXIT 

ELSE 

3 

EDTABT 

ELSE 

4 

UPCUR 

ELSE 

5 

DNCUR 

ELSE 

6 

LFCUR 

ELSE 

7 

RTCUR 

ELSE 

a 

RUB 

ELSE 

9 

LNINS 

ELSE 

10 

LNDEL 

ELSE 

11 

SPLCHR 

ELSE 

12 



13 



14 


--> 

15 


( Main loop of editor > 
BEGIN 

KEY DUP LSTCHR ! 
?ESC 0 
IF 

PTCHR 0 LSTCHR ! 
ELSE 

CONTROL 
END IF 

LSTCHR 0 19 = 

UNTIL 


VI.0 ) 


==> 


Screen: 152 


0 

1 

£ 

( ValFORTH Video editor VI.0 ) 

0 

i 

( ValFORTH Video editor VI.0 

PTCHR 

( IF NOTHING SPECIAL ) 

1 

o 

u. 

CBLANK SCRSV 0 767 C! 

3 

ENDIF 

ENDIF ENDIF ENDIF 

3 

£ 560 0 6 + Ci 

4 

END IF 

ENDIF ENDIF ENDIF 

4 

£ 56® 0 £3 + C! 

5 

ENDIF 

ENDIF ; 

5 

£ 559 C@ £52 

6 



6 

AND OR 559 C! 

7 



7 

0 752 C! CLS CR 

8 



8 

." Last edit on screen # " 

9 



9 

SCR 0 . CR CR ; 

10 



10 


11 



1 1 

FORTH DEFINITIONS 

12 



12 


13 



13 

: V ( s — 

14 



14 

1 MAX B/SCR * 

15 


==> 

15 

EDITOR (V) ; 



Screen: 156 

0 ( ValFORTH Video editor VI.0 ) 
1 

£ : L ( — ) 

3 SCR 0 DUP 1+ 

4 B/SCR * SWAP B/SCR * 

5 EDITOR TBLK <? DUP <ROT 

6 <« <ROT > AND 

7 IF 

8 EDITOR TBLK 0 

9 ELSE 

10 SCR 0 B/SCR * 

11 ENDIF 

IS EDITOR (V) ; 

13 

14 

15 ==> 


Screen: 159 
0 
1 
£ 

3 

4 

5 

6 
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8 
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11 

1£ 
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14 
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Screen: 157 

0 < ValFORTH Video editor VI.0 ) 
1 

£ : CLEAR ( s -- ) 

3 B/SCR * B/SCR O+S 

4 DO 

5 FORTH I BLOCK 

6 B/BUF BLANKS UPDATE 

7 LOOP ; 

8 

9 : COPY ( si s£ — ) 

10 B/SCR * OFFSET @ + 

11 SWAP B/SCR * B/SCR O+S 

1£ DO DUP FORTH I 

13 BLOCK £- ! 

14 1+ UPDATE 

15 LOOP DROP ; —> 


Screen: 160 
0 
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4 
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1£ 
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Screen: 158 

0 ( ValFORTH Video editor 
1 


VI.0 ) 


Screen: 
0 


161 


£ 



£ 

3 

( 

Note: the fig bug is fixed ) 

3 

4 

( 

in WHERE below. ) 

4 

er 

6 

HEX 

j 

6 

7 

* 

« 

WHERE ( C n n : — ) 

7 

8 


£DUP DUP B/SCR / DUP SCR ! 

8 

9 


. " Scr # " DECIMAL . SWAP 

9 

10 


C/L /MOD C/L * ROT BLOCK + 

10 

11 


CR C/L -TRAILING TYPE 

11 

1£ 


CR HERE C@ - £- 0 MAX SPACES 

1£ 

13 


1 £FE C! 1C EMIT 0 £FE C! 

13 

14 


[COMPILE! EDITOR QUIT ; 

14 

15 


BASE ! 

15 



Screen: 16£ 

0 < DOS: input/output routines 
1 

£ BASE @ HEX 

3 

4 340 VARIABLE IOCB 


Screen: 165 

0 ( DOS: GET/PUTREC STATUS DEV ) 
1 

£ : GETREC ( adr nl n£ — n3 ) 

3 IOCC 5 ICCOM C! ICELL i 
ICBAL ! XCIO : 


D 

6 

7 

B 

9 

10 

11 


0 VARIABLE 10.X 
0 VARIABLE 10.CH 

IOCC 

10 * 70 MIN DUP 10. X C! 
340 + IOCB ! : 


4 

5 

6 
7 

a 

9 

10 

11 


PUTREC ( adr nl n£ — n3 ) 

IOCC 9 ICCOM Ci ICBLL ! 

ICBAL ! XCIO : 


STATUS 

IOCC ICSTA C0 


< nl — n£ ) 


i£ 

■ 

• 

<I0> 


12 






13 


<BUILDS , 


13 

M 

m 

DEVSTAT 

( nl 

— ri£ n3 

n4 ) 

14 


DOES) @ IOCB 0 + ; 


14 


IOCC 0D 

ICCOM C! 

XCIO 


15 


= 

= > 

15 


> R 2EA & 

£EC @ R> 

5 

—> 

Screen: 163 


Screen 

i: 166 




0 

( 

DOS: system words 

) 

0 

( 

DOS: SPECIAL 


) 

1 




1 






£ 

o 

l_ 

<I0> ICCOM 3 <I0> ICSTA 


c! 

a 

a 

SPECIAL 




3 

4 

<I0> ICBAL 8 <I0> ICBLL 



( 

n1 n£ m3 

n4 n5 n6 

n7 nS — 

- r.9> 

4 

A 

<I0> ICAX1 B <I0> ICAX£ 


4 


IOCC ICCOM C! ICAX6 C! 


5 

C 

<I0> ICAX3 D <I0> ICAX4 


5 


ICAX5 C! 

ICAX4 C! 

ICAX3 C! 


6 

E 

<I0> ICAX5 F <I0> ICAX6 


6 


ICAX2 C! 

ICAX1 C! 

XCIO ; 


“7 

t 




7 






8 




8 






9 

CODE XCIO 


9 






10 


XSAVE STX, 10.X LDX, 


10 






11 


10.CH LDA, E456 JSR, 


11 






12 


XSAVE LDX, 10.CH STA, 


1 £ 






13 


TYA, PUSH0A JMP, 


13 






14 

C; 



14 






15 



-> 

15 




BASE ! 


Screen 

i: 164 


Screen 

: 167 




0 

( 

DOS: OPEN CLOSE PUTC GETC 

) 

0 






1 




1 






£ 

■ 

M 

OPEN ( adr nl ri£ n3 — n4 

) 

£ 








IOCC ICAX£ C! ICAX1 C! 


■Jj 






4 


ICBAL ! 03 ICCOM C! XCIO ; 


4 






cr 

wJ 




5 






6 

■ 

m 

CLOSE ( r.l -- 

) 

6 







7 

a 

9 

10 
11 
1£ 

13 

14 

15 


IOCC 0C ICCOM C! XCIO DROP ; 


PUT 

IOCC 10.CH C! 0B 
ICCOM C! XCIO ; 


< c nl — n£ ) 


GET ( nl — c n£ ) 

IOCC 7 ICCOM C! XCIO 

10.CH C@ SWAP ; ==> 


7 

a 

9 
10 
11 
1 £ 

13 

14 

15 



Screen: 168 





Screen: 171 


0 

1 

< Atari 850 

download 


) 

0 

1 

CONTENTS OF THIS DISK 

, cont: 

X 

£ 

BASE 0 HEX 





1 

2 

fig EDITOR: 

56 LOAD 

3 






3 

BUFFER RELOCATION: 

94 LOAD 

4 

CODE DO-SIO 





4 

AUTO-BOOT UTILITY: 

30 LOAD 

5 

XSAVE STX, 

0 # LDA, 



5 

OPERATING SYS. WORDS: 

162 LOAD 

6 

E459 JSR, 





6 

850 DOWNLOAD (RS-232) 

: 168 LOAD 

7 

XSAVE LDX, 

NEXT 

JMP, 



7 

(OPSYS AND 850 NEED 

ASSEMBLER) 

8 






8 



9 

: SET-DCB 





9 



10 

50 300 Ci 

1 

301 

C! 


10 



11 

3F 302 Ci 

40 

303 

C! 


11 



12 

500 304 ! 

5 

306 

C! 


12 



13 

0 307 C! 

C 

308 

C! 


13 



14 

0 309 ! 

0 

30B 

C! ; 


14 



15 





==> 

15 




Screen: 169 

Screen: 172 

0 

< Atari 850 download ) 

0 

1 


1 

2 

CODE RELOCATE 

£ 

3 

XSAVE STX, 506 JSR, 

3 

4 

HERE 8 + JSR, XSAVE LDX, 

4 

5 

NEXT JMP, 0C ) JMP, 

5 

6 


6 

7 


7 

8 

: RS232 ( — ) 

8 

9 

HERE 2E7 ! SET-DCB DO-SIO 

9 

10 

500 300 0C CMOVE DO-SIO 

10 

11 

RELOCATE 2E7 0 HERE - ALLOT 

11 

12 

HERE FENCE ! ; 

12 

13 


13 

14 


14 

15 

BASE ! 

15 


Screen: 170 

0 CONTENTS OF THIS DISK: 

1 

£ PRINTER UTILITIES: 

38 LOAD 

Screen: 173 
0 

1 

cl 

3 

DEBUGGING AIDS: 

42 LOAD 

Jj 

4 

VALFORTH EDITOR 1.0: 

140 LOAD 

4 

5 

ASSEMBLER: 

76 LOAD 

5 

6 

COLOR COMMANDS: 

100 LOAD 

6 

7 

GRAPHICS: 

104 LOAD 

7 

8 

GRAPHICS DEMO: 

112 LOAD 

8 

9 

SOUNDS: 

114 LOAD 

9 

10 

FLOATING POINT: 

120 LOAD 

10 

11 

(FP REQUIRES ASSEMBLER 

FIRST) 

11 

12 

SCREEN CODE CONVERS.: 

136 LOAD 

12 

13 

FORMATTER: 

92 LOAD 

13 

14 

DISK COPIERS: 

72 LOAD 

14 

15 

(continued on next screen) 

15 



Screen: 174 
0 

1 

2 

3 

4 

5 

6 

7 

8 
9 

1® 

11 

12 

13 

14 

15 


Screens 177 
0 Disk Error! 

1 

2 Dictionary too big 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 


Screen: 175 
0 
1 
£ 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 


Screen: 178 

0 ( Error messages 
1 

2 Use only in Definitions 

3 

4 Execution only 

5 

6 Conditionals not paired 

7 

8 Definition not finished 

9 

10 In protected dictionary 

11 

12 Use only when loading 

13 

14 Off current screen 

15 


Screen: 176 

0 < Error messages 
1 

2 Stack empty 

3 

4 Dictionary full 

5 

6 Wrong addressing mode 

7 

8 Is not unique 

9 

10 Value error 

11 

12 Disk address error 

13 

14 Stack full 

15 


Screen: 179 

0 Declare VOCABULARY 
1 
£ 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 




valFORTH 

SOFTWARE SYSTEM 

GENERAL JTWTIES 


Strings 


Double Number Extensions 


UM0VE 

( addrl addr2 

1 n -- ) 

UM0VE is a "universal" memory move. It takes 
the block of memory n bytes long, at addrl and 
copies it to memory location addr2. UM0VE 
correctly uses either CM0VE or <CM0VE. 

" ccc" 

( - ) 

{ -- addr ) 


(at compile time) 

(at run time) 

If compiling, the sequence ccc (delimited by 
the trailing ") is compiled into the dictionary 
as a string: 

| len |clclcl...lcl 

SC0NSTANT 

xxx t 5 -- 


(at compile time) 


xxx: ( -* 

S ) 

(at execution time) 

Takes the string on top of the stack and 
compiles it into the dictionary with the name 
xxx. When xxx is later executed, the address 
of the string is pushed onto the'Stack. 

SVARIABLE 

xxx ( n — 

) 

Reserves space for a string of length n. 


xxx: ( 

S ) 

When xxx is later executed, the address of the 
string is pushed onto the stack. 

$. 

( $ - ) 


Takes the string on top of the stack and sends 
it to the current output device. 

$! 

( $ addr -- ) 


Takes the string at second on stack and stores 
it at the address on top of stack. 

$+ 

( $1 $2 - 

S3 ) 

Takes $2 and concatenates it with SI, leaving 

S3 at PAD. 

LEFTS 

( SI n - 

S2 ) 

Returns the leftmost "n" characters of SI as 

52. 

Returns the rightmost "n" characters of $1 as 
$2. 

Returns $2 of length u starting with the nth 
character of $1. 

RIGHTS 

(SI n — 

S2 ) 

MIDS 

(SI n u 

- $2 ) 

LEN 

( S -- len ) 


Returns the length of the specified string. 

ASC 

( S ~ c ) 


Returns the ASCII value of the first character 
of the specified string. 

SC0MPARE 

( SI S2 - 

flag ) 

Compares $1 with $2 and returns a status flag. 

$= 

( SI 52 - 

flag ) 

Compares two strings on top of the stack. 

$< 

( SI S2 - 

flag ) 

Compares two strings on top of the stack. 

S> 

( SI S2 - 

flag ) 

Compares two strings on top of the stack. 

SAVES 

( SI -- S2 

) 

As most string operations leave resultant 
strings at PAD, the word SAVES is used to 
temporarily move strings to PAD+512. 

INSTR 

( SI S2 - 

n ) 

Searches $1 for first occurrence of $2. 

Returns the character position in SI if a 
match is found; otherwise, zero is returned. 

CHRS 

( c - S ) 


Takes the character "c" and makes it into a 
string of length one and stores it at PAD. 

DSTRS 

( d - S ) 


Takes the double number d and converts it to 
its ASCII representation as $ at PAD. 

STRS 

( r> - S ) 


Takes the single length number n and converts 
it to its ASCII representation as S at PAD. 

STRINGS 

( n SI — 

52 ) 

Creates $2 as n copies of the first character 
of SI. 

#IN$ 

( n - S ) 


#INS has three similar but different functions. 
If n is positive, it accepts a string of n or 
fewer characters from the terminal. If n is 
zero, it accepts up to 255 characters from the 
terminal. If n is negative, it returns only 
after accepting -n characters from the terminal. 
The resultant string is stored at PAD. 

INS 

( - S ) 


Accepts a string of up to 255 characters from 
the terminal. 

$-TB 

( SI - 52 

) 

Removes trailing blanks from $1 leaving new $2. 

SXCHG 

( SI -- S2 

) 

Exchanges the contents of SI with S2. 


Array Word Glossary 


ARRAY 


CARRAY 


TA8LE 


CTABLE 


VECTOR 


CVECTOR 


xxx ( n — ) 

xxx:( m -- addr ) 


xxx ( n -- ) 

xxx:( m — addr ) 


xxx ( — ) 

xxx:( m -- addr ) 


xxx ( — ) 

xxx:( m — addr ) 


xxx (nO ... nN count .. ) 
xxx:( m — addr ) 


xxx (bO ... bN count - 
xxx:( m — addr 


(compiling) 

(executing) 

When compiling, creates an array named xxx 
with n 16-bit elements numbered 0 thru n-1. 
Initial values are undefined. When executing, 
takes an argument, m, off the stack and leaves 
the address of element m of the array. 

(compiling) 

(executing) 

When compiling, creates a c-array named xxx 
with n 8-bit elements numbered 0 thru n-1. 

Initial values are undefined. When executing, 
takes an argument, m, off the stack and leaves 
the address of element m of the c-array. 
(compiling) 

(executing) 

When compiling, creates a table named xxx but 
does not allot space. Elements are compiled in 
directly with , (comma). When executing, takes 
one argument, m off the stack and, assuming 
16-bit elements, leaves the address of element 
m of the table. 

(compiling) 

(executing) 

When compiling, creates a c-table named xxx 
but does not allot space. Elements are compiled 
in directly with C, (c-comma). When executing, 
takes one argument, m off the stack and, assuming 
8-bit elements, leaves the address of element m 
of the c-table. 

(compiling) 

(executing) 

When compiling, creates a vector named xxx 
with count 16-bit elements numbered 0-N. nO is 
the initial value of element 0, nN is the 
initial value of element N, and so on. When 
executing, takes one argument, m, off the stack 
and leaves the address of element m on the stack. 
) (compiling) 

) (executing) 

When compiling, creates a c-vector named xxx 
with count 8-bit elements numbered 0-N. bO is 
the initial value of element 0, bN is the 
initial value of element N, and so on. When 
executing, takes an argument, m, off the stack 
and leaves the address of element m on the stack. 


DVARIABLE 

xxx ( d — ) 

xxx:( -- addr ) 

DCONSTANT 

xxx ( d — ) 

xxx:( — d ) 

D- 

D0= 

( dl d2 - d3 ) 

( d — flag) 

D= 

( dl d2 - flag ) 

D0< 

( d -- flag ) 

D< 

( dl 62 - flag ) 

D> 

( dl d2 -- flag ) 

DMIN 

DMAX 

D>R 

( dl d2 - d3 ) 

( dl d2 - d3 ) 

( d - ) 

DR> 

( - d ) 

D, 

( d - ) 

Dlk 

( udl ud2 — flag 

M+ 

( dl n — d2 ) 

High Resolution Text < 

GCINIT ( — ) 

GC. 

( n — ) 

GC.R 

( nl n2 - ) 

GCD.R 

( d n -- ) 

GCEMIT 

( c - ) 

GCLEN 

( addr n -- len 

GCR 

( - ) 

GCLS 

( - ) 

GCSPACE 

( - ) 

GCSPACES 

( n — ) 

GCTYPE 

( addr n -- ) 

GC" ccc" 

( - ) 

GCBKS 

( - ) 

GCPOS 

( horz vert -- ) 

GCS. 

( addr — ) 

SUPER 

( - ) 

SUB 

( - ) 

VMI 

( n — ) 

VMI# 

OSTRIKE 

( — addr ) 

( ON or OFF - ) 

GCBAS 

( -- addr ) 

GCLFT 

( -- addr ) 

GCRGT 

( -- addr ) 


At compile time, creates a double number 
variable xxx with the initial value d. At 
run time, xxx leaves the address of its value 
on the stack. 

At compile time, creates a double number 
constant xxx with the initial value d. At 
run time, xxx leaves the value d on the stack. 
Leaves dl-d2*d3. 

If d is equal to 0. leaves true flag; 
otherwise, leaves false flag. 

If dl equals d2, leaves true flag; otherwise, 
leaves false flag. 

If d is negative, leaves true flag; otherwise, 
leaves false flag. 

If dl is less than d2, leaves true flag; other¬ 
wise, leaves false flag. 

If dl is greater than d2, leaves true flag; 
otherwise, leaves false flag. 

Leaves the minimum of dl and d2. 

Leaves the maximum of dl and d2. 

Sends the double number at top of stack to the 
return stack. 

Pulls the double number at top of the return 
stack to the stack. 

Compiles the double number at top of stack 
into the dictionary. 

If the unsigned double number udl is less 
than the unsigned double number ud2, leaves a 
true flag; otherwise, leaves a false flag. 
Converts n to a double number and then sums 
with dl. 


Initializes the graphic character output 
routines. This must be executed prior to using 
any other hi-res output words. 

Displays the single length number n at the 
current hi-res cursor location. 

Displays the single length number nl right- 
justified in a field n2 graphic characters 
wide. See .R . 

Displays the double length number d right- 
justified in a field n graphic characters 
wide. See D.R . 

Displays the text character c at the current 
hi-res cursor location. Three special 
characters are interpreted by GCEMIT. 

Scans the first n characters at addr and 
returns the number of characters that will 
actually be displayed on screen. 

Repositions the hi-res cursor to the beginning 
of the next hi-res text line. See CR . 

Clears the hi-res display and repositions the 
cursor in the upper lefthand corner. 

Sends a space to the graphic character output 
routine. See SPACE . 

Sends n spaces to the graphic character output 
routine. See SPACES . 

Sends the first n characters at addr to the 
graphic character output routine. See TYPE . 
Sends the character string ccc (delimited by ") 
to the graphic character output routine. 

Moves the hi-res cursor back one character 
position for overstriking or underlining. 
Positions the hi-res cursor to the coordinates 
specified. Note that the upper lefthand corner 
is 0,0. 

Sends the string found at addr and preceded by 
a count byte to the graphic character output 
routine. See S. . 

Forces the graphic character output routine 
into the superscript mode (or out of the sub¬ 
script mode). See VMI below. May be performed 
within a string by the * character. 

Forces the graphic character output routine 
into the subscript mode (or out of the super¬ 
script mode). See VMI below. May be performed 
within a string by the v character. 

The VMI command sets the number of eighths of 
characters to scroll up or down when either a 
SUPER or SUB command is issued. 

A variable set by VMI. 

If the 0STRIKE option is ON, characters are 
printed over top of the previous characters 
giving the impression of overstriking. 

A variable which contains the address of the 
character set displayed by GCEMIT. To change 
character sets, simply store the address of 
your new character set into this variable. 

A variable which holds the column position of 
the left margin. 

A variable which holds the column position of 
the right margin. 
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Case Structures 

CASE: structure SEL Structure 


Format: 


Format: 


CASE: 

wordname 

wordO 

: wordname 


wordl 

SEL 



nl -> wordO 


wordN ; 

n2 -> wordl 

CASE Structure 


nN > wordN 



( NOSEL wordnone 

Format: 


SELEND 

wordname 


COND Structure 

CASE 



wordO 


Format: 


wordl 

wordN 

( NOCASE wordnone ) 
CASENO 


wordname 

COND 

conditionO « 
condition 1 « 


wordsO 
words 1 


» 

» 


( 


conditionN « wordsn » 
NOCOND wordsnone ) 

CONDEND 




Miscellaneous Utilities 


XR/W 

( fsecs addr blk flag — 

LOADS 

( start count — ) 

THRU 

( start finish — 

start count 

SEC 

( n — ) 

MSEC 

( n - ) 

H->L 

( nl — n2 ) 

L->H 

( nl - n2 ) 

H/L 

( nl — nl(hi) nl(lo) ) 

BH 

( b — n ) 

?B IT 

( n b — f ) 

TBIT 

( nl b — n2 ) 

SB IT 

( nl b — n2 ) 

RBIT 

( nl b — n2 ) 

STICK 

( n — horz vert ) 

PADDLE 

( nl - n2 ) 

16TIME 

( — n ) 

8RND 

( - b ) 

16RND 

( -- n ) 

CHOOSE 

( ul - u2 ) 

CSHUFL 

( addr n — ) 

SHUFL 

( addr n — ) 

DUMP 

( addr n — ) 

BXOR 

( addr count b -- ) 

BAND 

( addr count b — ) 

BOR 

( addr count b - ) 

STRI6 

( n — flag ) 

PTRIG 

( n — flag ) 


) "Extended read-write." The same as R/W except 
that XR/W accepts a sector count for multiple 
sector reads and writes. Starting at address 
addr and block blk, read (flag true) or write 
(flag false) teecs sectors from or to disk. 

Loads count screens starting from screen § 
start. 

Converts two range numbers to a start-count 
) format. 

Provides an n second delay. Uses a tuned 
do-loop. 

Provides an n millisecond delay, (approx) 

Uses a tuned do-loop. 

Moves the high byte ofnlto the low byte and 
zero's the high byte, creating n2. Machine 
code. 

Moves the low byte of nl to the high byte and 
zero's the low byte, creating n2. Machine code. 
Split top of stack into two stack items: 

New top of stack is low byte of old top of 
stack. New second on stack is old top of 
stack with low byte zeroed. 

Creates a number n that has only its bth bit 
set. The bits are numbered 0-15. 

Leaves a true flag if the bth bit of n is set. 
Otherwise leaves a false flag. 

Toggles the bth bit of nl, making n2. 

Sets the bth bit of nl, making n2. 

Resets the bth bit of nl, making n2. 

Reads the nth stick (0-3) and resolves the 
setting into horizontal and vertical parts, 
with values from -1 to +1. -1-1 means up 

and to the left. 

Reads the nlth paddle (0-7) and returns its 
value n2. Machine code. 

Returns a 16 bit timer reading from the system 
clock at locations 19 and 20, decimal. 

Leaves one random byte from the internal 
hardware. Machine code. 

Leaves one random word from the internal 
hardware. Machine code with 20 cycle extra 
delay for rerandomization. 

Randomly choose an unsigned number u2 which 
is less than ul. 

Randomly rearrange n bytes in memory, start¬ 
ing at address addr. 

Randomly rearrange n words in memory, start¬ 
ing at address addr. 

Starting at addr, dump at least n bytes (even 
multiple of 8) as ASCII and hex. May be 
exited early by pressing a CONSOLE button. 
Starting at address addr, for count bytes, 
perform bit-wise exclusive OR with byte b at 
each address. 

Starting at address addr, for count bytes, 
perform bit-wise AND with byte b at each 
address. 

Starting at address addr, for count bytes, 
perform bit-wise OR with byte b at each address. 
Reads the button of joystick n (0-3). 

Reads the button of paddle n (0-7). 
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Placement of Tabs for Utilities/Editor Documentation 

The tab titles included should be cut apart and inserted into the tabs 
in the following order, starting at the fifth position: 

* valFORTH ED. 1.1 Locate before section XI 

* $-ARY-CA$E-DBL Locate before section XII 


* HRT-MSC-TRNS 


Locate before section XIII 
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Version 1.1 
March 1982 


The FORTH language is a very powerful addition to the Atari home computer. 
Programs which are impossible to write in BASIC (usually because of limitations 
in speed and flexibility) can almost always be written in FORTH. Even when one 
has mastered the BASIC language, making corrections or additions to programs 
can be tedious. The video editor described here removes this problem from 
the FORTH environment. Similar to the MEMO PAD function in the Atari operating 
system, this editor makes it possible to insert and delete entire lines of code, 
insert and delete single characters, toggle between insert and replace modes, 
move entire blocks of text, and much more. 
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Purchasers of this software and documentation package are 
authorized only to make backup or archival copies of the 
software, and only for personal use. Copying the accompanying 
documentation is prohibited. 

Copies of software for distribution may be made only as speci¬ 
fied in the accompanying documentation. 




VALPAR INTERNATIONAL 


Disclaimer of Warranty 
on Computer Programs 


All Valpar International computer programs are distributed 
on an “as is" basis without warranty of any kind. The total 
risk as to the quality and performance of such programs is with 
the purchaser. Should the programs prove defective following 
their purchase, the purchaser and not the manufacturer, distributor, 
or retailer assumes the entire cost of all necessary servicing or 
repair. 

Valpar International shall have no liability or responsibility 
to a purchaser, customer, or any other person or entity with 
respect to any liability, loss, or damage caused directly or 
indirectly by computer programs sold by Valpar International. 

This disclaimer includes but is not limited to any interruption 
of service, loss of business or anticipatory profits or conse¬ 
quential damages resulting from the use or operation of such 
computer programs. 

Defective media (diskettes) will be replaced if diskette(s) 
is returned to Valpar International within 30 days of date of sale 
to user. 

Defective media (diskettes) which is returned after the 30 day 
sale date will be replaced upon the receipt by Valpar of a $12.00 
Replacement Fee. 
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Overview 

This editor is a powerful extension to the valFORTH system designed 
specifically for the Atari 400/800 series of microcomputers. The main purpose 
for this editor is to give the FORTH programmer an easy method of text entry to 
screens for subsequent compilation. The editor has four basic modes of opera¬ 
tion: 

1} It allows entering of new text to a FORTH screen as though 
typing on a regular typewriter. 

2) It allows quick, painless modification of any text with a 
powerful set of single stroke editing commands. 

3) It pinpoints exactly where a compilation error has occurred 
and sets up the editor for immediate correction and 
recompilation. 

4) Given the name of a precompiled word, it locates where the 
original text definition of the word is on disk, if the 
"LOCATOR" option had been selected when the word was compiled. 

The set of single stroke editing commands is a superset of the functions 
found in the MEMO PAD function of the standard Atari operating system. In 
addition to cursor movement, single character insertion/deletion, and line 
insertion/deletion, the editor supports a clear-to-end-of-1ine function, a 
split command which separates a single line into two lines, and a useful insert 
submode usually found only in higher quality word processors. 

In addition, there are provisions for scrolling both forwards and backwards 
through screens, and to save or "forget" any changes made. This is useful at 
times when text is mistakenly modified. 

Also provided is a visible edit storage buffer which allows the user to 
move, replace, and insert up to 320 lines of text at a time. This feature alone 
allows the FORTH programmer to easily reorganize source code with the added 
benefit of knowing that re-typing mistakes are avoided. Usage has shown that 
once edit-buffer management is learned, significant typing and programming 
time can be saved. 

For those times when not programming, the editor can double as a simple 
word processor for writing letters and filling other documentation needs. 

The best method for learning how to use this powerful editor is to enter the 
edit mode and try each of the following commands as they are encountered in 
the reading. 

As stated above, there are four ways in which to enter the video editor. 

The following four commands explain each of the possibilities. Note that the 
symbol "<ret>" indicates that the "RETURN" key is to be typed. 
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view screen ( scr# — 

To edita screen for the first time, the "View" command is to be 
used. The video display will enter a 32 character wide mode and will 
be broken into three distinct sections. For example, 

50 V <ret> 

should give something like the display shown in fig. 1. 


Screen #50 U #Bufs: 5 


■ ( Example screen 

) ( line 0 ) 

: TEST1 

10 0 

DO 

I CR . 

LOOP ; 

( line 2 ) 

: OCTAL 

8 BASE ! ; 

( — ) 

: +C! 

DUP C@ ROT + 
SWAP C! ; 


( 

bottom line ) 


Fig. 1 


The top window, composed of a single line, indicates in decimal 
which screen is currently being edited. One should always make a 
practice of checking this screen number to insure that editing will be 
done on the intended screen. Often times, when working with other 
number bases, the wrong screen is called up accidentally and catching 
this mistake early can save time. Also shown is the size of the edit 
buffer (described later). In this example, the buffer is five lines in 
length. This window is known as the heading window. 
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FORTH screens typically are IK (1024 characters) long. Since it is 
impossible to see an entire screen simultaneously, this editor reveals 
only half a screen at a time. There is an "upper" half and a "lower" 
half. In the center of the heading window, either a "U" or an "L" 
is displayed indicating which half of the current screen is being viewed. 
If the valFORTH system is in the half-K screen mode, neither "U" nor "L" 
is displayed since an entire half-K screen can be viewed at one time. 

In figure 1, the upper half of a full-K screen is being viewed. 

The second window (the text window) contains the text found on the 
specified screen. This window is 32 characters wide and 16 lines high. 
The white cursor (indicated by the symbol "«") will be in the upper- 
lefthand corner of the screen awaiting editing commands. 

The final five-line window found at the bottom of the screen is 
known as the buffer window. This is used for advanced editing and is 
described in greater detail in the section entitled "Buffer Management." 


L re-edit last screen ( — ) 

This command is used to re-edit the "Last" screen edited. It 
functions identically to the "V" command described above, except no 
screen number is specified. 

Example: L <ret> (re-edit screen 50) 


WHERE find location of error ( — ) 

If, when compiling code, a compilation error occurs, the WHERE 
command will enter the edit mode and position the cursor over the last 
letter of the offending word. The word can then be fixed and the screen 
can be re-compiled. Bear in mind that using the WHERE command prior to 
any occurrence of an error could give strange results. 


LOCATE locate definition cccc ( — ) 

Once source text has been compiled into the dictionary, it loses 
easy readability to all but experts of the FORTH language. Often times, 
though, it is helpful to see what the original source code was. The 
DECOMP command found in the debugger helps tremendously in this regard, 
however, some structures such as IF and DO are still difficult to follow. 
For this reason, the LOCATE command is included with the editor. 

This command accepts a word name, and if at all possible it will 
actually direct the editor to load in the screen where that word was 
defined. This is very helpful at times when one cannot remember where 
the original text was. If the screen shown in figure 1 were loaded and 
the command 

.LOCATE +C! <ret> 

were given, the editor would call up screen 50 and position the cursor 
over the word which is the beginning of the definition for "+C!". 
Typically, the LOCATE command will point to , "CODE" , "CONSTANT" , 
and other defining words. 
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There is a drawback to this feature, however. In order to call up 
any word, the LOCATE command must know where the word actually is. 
Normally, when a word is compiled, there is no way of knowing where it 
was loaded from. Thus for the LOCATE command to work, each time a word 
is entered into the dictionary, three extra bytes of memory must be used 
to store this lookup information. For an application with many words, 
these extra bytes per word add up quickly, and this is not always 
desirable. For this reason, the LOCATOR command (described below) 
allows the user to enable or disable the storage of this lookup informa¬ 
tion. Only words that were compiled with the LOCATOR option selected 
can be located. If a word cannot be located, the user is warned, or if 
the DEBUGGER is loaded, the word is DECOMPed giving pseudo original code. 


LOCATOR enable/disable location ( ON/OFF — ) 


In order for a word to be locatable using LOCATE, the LOCATOR option 
must have been selected prior to compiling the word. The LOCATOR option 
is selected by executing "ON LOCATOR" and deselected by executing "OFF 
LOCATOR". For example: 


ON LOCATOR 
: PLUS ."="+. 

: STAR 42 EMIT ; 

OFF LOCATOR 
: NEGATE MINUS ; 


(partial view of a screen) 


Only the words PLUS and STAR can be located. NEGATE cannot be located 
since the LOCATOR option was disabled. If the DEBUGGER were loaded, 
NEGATE would be decompiled (see the debugger), otherwise, the user would 
be given a warning. The default value for LOCATOR is OFF. 


#BUFS set buffer length ( #lines — ) 

The #BUFS command allows the user to specify the length (in terms of 
number of lines) of the special edit storage buffer. The power of the 
edit buffer lies in the number of lines that can be stored in it. 

Although the default value is five, practice shows that at least 16 
lines should be set aside for this buffer. The maximum number of lines 
allowable is 320which is enough to hold 20 full screens simultaneously. 
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The following sections give a detailed description of all commands which 
the video editor recognizes. A quick reference command list can be found 
following these descriptions. 

Cursor Movement 

When the edit mode is first entered via the "V" command, a cursor is placed 
in the upper lefthand corner of the screen. It should appear as a white block 
and may enclose a black letter. Whenever any key is typed and it is not recog¬ 
nized as an editor command, it is placed in the text window where the cursor 
appears. Likewise, any line functions (such as delete line) work on the line 
where the cursor is found. 


Ctrl a , Ctrl v , Ctrl «, Ctrl > move-cursor commands 

To change the current edit line or character, one of four commands 
may be given. These are known as cursor commands. They are the four 
keys with arrows on them. These keys move the cursor in the direction 
specified by the arrow on the particular key pressed. There are times, 
however, when this is not the case. 

If the current cursor line is the topmost line of the text window, 
and the "cursor-up" command is issued (by simultaneously typing "ctrl" 
and "up-arrow"), the cursor will move to the bottom line of the text 
window. Likewise, a subsequent "cursor-down" command would return the 
cursor to the topmost line of the window. Similarly, if the cursor is 
positioned on the leftmost edge and the "cursor-left" command is given, 
the cursor will "wrap" to the rightmost character ON THE SAME LINE. 

Issuing "cursor-right" will wrap back to the first character on that line. 


RETURN next-line command 

Normally, the RETURN key positions the cursor on the first character 
of the next line. If RETURN is pressed when the cursor is on the last 
line of the text window (i.e., when the last text line of the screen is 
current), the cursor is positioned in the upper lefthand corner of the 
screen. 


TAB tabulate command 

The TAB key is used to tabulate to the next fixed four column 
tabular stop to the right of the current cursor character. TABbing off 
the end of the current line simply places the cursor at the beginning of 
that same line. 


NOTE: 


Many commands in the editor will "mark" a current FORTH screen as updated 
so that any changes made can be preserved on disk. As simple cursor movement 
does not change the text window in any way, these commands never mark the 
current FORTH screen. See the section on screen management for more informa¬ 
tion. 
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Editing Commands 

Editing commands are those commands which modify the text in some 
predefined manner and mark the current FORTH screen as updated for later 
saving. 


character insert command 

When the "insert-character" command is given, a blank character 
is inserted at the current cursor location. The current character and 
all characters to the right are pushed to the right by one character 
position. The last character of the line "falls off" the end and is 
lost.. The inserted blank then becomes the current cursor character. 
This is the logical complement to the "delete-character" command 
described below. 


DtL delete character command 

When the "delete-character" command is issued, the current cursor 
character is removed, and all characters to the right of the current 
cursor character are moved left one position, thus giving a "squeeze" 
effect. This is normally_called "closing" a line. The rightmost 
character on the line (which was vacated) is replaced with a blank. 

This serves as the logical complement to the "insert-command" described 
above. 


shift INS line insert command 

The "line-insert" command inserts a blank line between the current 
cursor line and the line immediately above it. The current line and all 
lines below it are moved down one line to make room for the new line. 

The last line on the screen falls off the bottom and is lost. If this 
command is accidentally typed, the "oops" command (ctrl-0) described 
later can be used to recover from the mistake. Also see the "from buffer" 
command described in the section on buffer management for a similar command. 
This command serves as the logical complement to the "line-delete" command 
described below. 


shift DEL line delete command 

The "line-delete" command deletes the current cursor line. All 
lines below the current line are brought up one line and a blank' line 
fills the vacated bottom line of the text window. The deleted line is 
lost. If this command is accidentally issued, recovery can be made by 
issuing the "oops" command (ctrl-0) described later. Also see the 
"to-buffer" command described in the section on buffer management for a 
similar command. The "delete-line" command serves as the logical comple¬ 
ment to the "line-insert" command. 
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Ctrl H erase to end of line 

The "Hack" command performs a clear-to-end-of-1ine function. The 
current cursor character and all characters to the right of it on the 
current line are blank filled. All characters blanked are lost. The 
"oops" command described later can be used to recover from an accidentally 
hacked line. 


Ctrl I insert/replace toggle 

In normal operation, any key typed which is not recognized by the 
editor as a control command will replace the current cursor character 
with itself. This is the standard replace mode. Normally, if one 
wanted to insert a character at the current cursor location, the insert 
character command would have to be issued before any text could be 
entered. If inserting many characters, this is cumbersome. 

When active, the insert submode automatically makes room for any 
new characters or words and frees the user from having to worry about 
this. When the editor is called up via the "V" command, the insert mode 
is deactivated. Issuing the insert toggle command will activate it and 
the cursor will blink, indicating that the insert mode is on. Issuing 
the command a second time will deactivate the insert mode and restore' 
the editor to the replace mode. Note that while in the insert mode, all 
edit commands (except BACKS, below) function as before. 


BACKS delete previous character 

The BACKS key behaves in two different ways, depending upon whether 
the editor is in the insert mode or in the replace mode. When issued 
while in the replace mode, the cursor is backed up one position and the 
new current character is replaced with a blank. If the cursor is at the 
beginning of the line, the cursor does not move, but the cursor character 
is still replaced with a blank. 

If the editor is in the insert mode, the cursor backs up one 
position, then deletes the new current cursor character and then closes 
the line. If the cursor is at the beginning of the line, the cursor 
remains in the same position, the cursor character is deleted and the 
line closed. 


NOTE: 


As all of the above commands modify the text window in some manner, the 
screen is marked as having been changed. This is to be sure that all changes 
made are eventually saved on disk. The "quit" command described in the section 
on changing screens allows one to unmark a screen so that major mistakes need 
not be saved. 
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Buffer Management 

Much of the utility of the valFORTH editor lies in its ability to tempo¬ 
rarily save text in a visible buffer. To aid the user, it is possible to 
temporarily send text to the buffer and to later retrieve it. This storage 
buffer can hold as many as 320lines of text simultaneously. This buffer is 
viewed through a 5 line "peephole" visible as the last window on the screen. 
Using this buffer, it is possible to duplicate, move, and easily reorganize 
text, in addition to temporarily saving a line that is about to be edited so 
that the original form can be viewed or restored if necessary. The following 
section will explain exactly how to accomplish each of these actions. 


Ctrl T to buffer command 

The "to-buffer" command deletes the current cursor line, but 
unlike the "delete-line" command where the line is lost, this command 
moves the "peephole" down and copies the line to the bottom line of the 
visible buffer window. This line is the current buffer line. The buffer 
is rolled upon each occurrence of this command so that it may be used 
repeatedly without the loss of stored text. 

For example, if the cursor is positioned on line eight of the display 
shown in figure 1 and the "to-buffer" command is issued twice, the final 
result will be as shown in figure 2. 


Ctrl F from buffer command 

The "from-buffer" command does exactly the opposite of the "to- 
buffer" command described above. It takes the current buffer line and 
inserts it between the current cursor line and the line above it. The 
cursor line and all lines below it are moved down one line with the last 
line of the text window being lost. If the cursor were placed on line 14 
of the above screen display and the "from-buffer" command were issued once, 
the display in figure 3 would result. 
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_ ^ 

Screen #50 U #Bufs: 5 


Current: 


( Example screen ) ( line 0 ) 

: TEST1 ( line 2 ) 

10 0 
DO 

I CR . 

LOOP ; 


: +C1 

DUP C@ ROT + 

SWAP C! ; 

■ 8 BASE ! ; 

{ bottom line ) 


line was 
rolled to 
the top 

8 BASE ! ; 


Current: 

: OCTAL 

( — ) 



fig. 3 

If the "from-buffer" command is issued again, t 
through 15 of the text window would look like: 

Current: 

: OCTAL 

8 BASE ! ; 

( — ) 

( bottom Tine ) 


fig. 4 


Note that a block of text has been moved on the screen, 
blocks of text can be moved in the same manner. - 


Larger 
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Ctrl K copy to buffer command 

The "copy-to-buffer" command takes the current cursor line and 
duplicates it, sending the copy to the buffer. This commands functions 
identically to the "to-buffer" command described above, except that the 
current cursor line is NOT deleted from the text window. 


Ctrl U - copy from buffer 

The "copy-from-buffer" command replaces the current cursor line with 
the current buffer line. This command functions identically to the "from- 
buffer" command described above, except that the buffer line is not inserted 
into the text window, it merely replaces the current cursor line. The 
"oops" command described below can be used to recover from accidental 
usage of this command. 


Ctrl R 


roll buffer 


The "rol1-buffer" command moves the buffer "peephole" down one line 
and redisplays the visible window. If the buffer were the minimum five 
lines in length, the bottom four lines in the window would move up a line 
and the top line would "wrap" to the bottom and become the current buffer 
line. If there were more than five buffer lines, the bottom four lines 
would move up a line, the topmost line would be pushed up behind the 
peephole, and a new buffer line coming up from below the peephole would 
be displayed and made current. For example, if the buffer were five lines 
long and contained: 


Current: 


( 

Who? 

) 

( 

What? 

) 

( 

When? 

) 

( 

Where? 

) 

( 

Why? 

) 


Fig. 5 


the "roll-buffer" command gives: 


Current: 


( What? 

) 

( When? 

) 

( Where? 

) 

( Why? 

) 

( Who? 

) 


Fig. 6 

Vw 
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Ctrl B back-rol1-buffer command 

The "back-roll-buffer" does exactly the opposite of the "roll- 
buffer" command described above. For example, if given the buffer in 
figure 6 above, the "back-roll" command would give the buffer shown in 
figure 5. 


Ctrl C clear buffer line command 

The "clear-buffer-line" command clears the current buffer line and 
then "back-rolls" the buffer so that successive clears can be used to 
erase the entire buffer. 


NOTE: 


Any of the above commands which change the text window will mark the 
current screen as updated. Those commands which alter only the buffer window 
(such as the "roll" command) will not change the status of the current screen. 
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Changing Screens 

There are four ways in which to leave a FORTH screen. These four methods 
are: moving to a previous screen, moving to a following screen, saving the 
current screen and exiting, or simply aborting the edit session. The four 
commands allowing this are now described: 


Ctrl P previous screen command 

The "previous-screen" command has two basic functions. If the lower 
part of the current screen is being viewed in the text window, this 
command simply displays the upper portion of the screen. If the upper 
portion is already being viewed, then the "previous-screen" command saves 
any changes made to the current screen and then loads in the screen 
immediately before the current screen. The lower part of the screen 
will then be displayed. If in the half-K screen mode, however, this 
command simply changes screens. 


Ctrl N next screen command 

Like the "previous-screen" command described above, the "next-screen" 
command also has two basic functions. If the upper part of a screen is 
being viewed, this command simply displays the lower portion. If, on the 
other hand, the lower part of the screen is being edited, any changes made 
to the current screen are saved and the next screen is loaded. 


Ctrl S save command 

The "save" command saves any changes made to the current screen and 
exits the edit mode. The video screen is cleared, and the number of the 
screen just being edited is displayed for reference. Note that it is 
usually a good idea to immediately FLUSH {described in the section on 
screen management below) any unsaved screens. 


Ctrl Q quit command 

The "quit" command aborts the edit session "forgetting" any changes 
made to the text visible in the text window. Changes made on previously 
edited screens will NOT be forgotten. The "quit" command is usually 
used when either the wrong screen has been called up, or if it becomes 
desirable to start over and re-edit the screen again. 
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Special Commands 

There are four special commands in this editor which allow greater flexi¬ 
bility in programming on the valFORTH system: 


ESCAPE special key command 

The "special-key" command instructs the video editor to ignore 
any command function of the key typed next and force a character to the 
screen. For example, normally when "ctrl »" is typed, the cursor is 
moved right. By typing "ESCAPE Ctrl >" the cursor is not moved — 
rather, the right-arrow is displayed. 


Ctrl A arrow command 

When dealing with FORTH screens, it is often necessary to put the 
FORTH word (pronounced "next screen") or the ValFORTH word "==>" 

(pronounced "next screen") or the ValFORTH word "==>" (pronounced "next 
half-K screen") at the end of a screen for chaining a long set of words 
together. This command automatically places, or erases, an arrow in the 
lower right hand corner of the text window. If is already there, 

it is replaced with "==>". If "==>" is found, it is erased. (This 
command marks the screen as updated.) 


Ctrl J 


split line command 


Often times, for formatting reasons, it is necessary to "split" a 
line into two lines. The split line command takes all characters to the 
left of the cursor and creates the first line, and with the remaining 
characters of the original line, a second line is created. Graphically, 
this looks like: 

before: | The quick*brown fox jumped. | 


after: | The quick* j 

I brown fox jumped. I 

Since a line is inserted, the bottom line of the text.window is lost. 
Using the "oops" command below, however, this can be recovered. 
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Ctrl 0 


oops command 


Occasionally, a line is inserted or deleted accidentally, half a 
line cleared by mistake, or some other major editing blunder is made. 
As the name implies, the "oops" command corrects most of these major 
editing errors. The "oops" command can be used to recover from the 
following commands: 


1) insert line command 

2) delete line command 

3) hack command 

4) to buffer command 

5) from buffer command 

6} copy from buffer command 
7} split line command 


(shift INS) 
(shift DEL) 
(ctrl H) 
(ctrl T) 
(Ctrl F) 
(ctrl U) 
(ctrl J) 
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Screen Management 

In addition to the commands available while in the edit mode, there are 
several other commands which are for use outside of the edit mode. Typically, 
these commands deal with entire screens at a time. 


FLUSH ( ... ) 

When any changes are made to the current text window, the current 
screen is marked as having been changed. When leaving the edit mode 
using the "save" command, the current screen is sent to a set of internal 
FORTH buffers. These buffers are not written to disk until needed for 
other data. Thus, if no other screen is ever accessed, the buffers will 
never be saved to disk. The FLUSH command forces these buffers to be 
saved if they have been marked as being modified. 

Example: FLUSH <ret> 


EMPTY-BUFFERS ( ___ ) 

Occasionally, screens are modified temporarily or by accident, and 
get marked as being modified. The EMPTY-BUFFERS command unmarks the 
internal FORTH buffers and fills them with zeroes so that "bad" data are 
not saved to disk. Zero filling the buffers ensures that the next access 
to any of the screens that were in the buffers will load the 
unadulterated copy from disk. The abbreviation MTB is included in the 
valFORTH system to make the use of this command easier. 

Examples: EMPTY-BUFFERS <ret> 

MTB <ret> 


COPY ' ( from — ) 

To duplicate a screen, the COPY command is used. The screen "from" 
is copied to the screen "to" but not flushed. 

Example: 51 60 COPY <ret> 

(Copies screen 51 to screen 60.) 

CLEAR (sc r# — ) 

The CLEAR command fills the specified screen with blanks so that a 
clean edit can be started. The screen is then made current so that the 
L command can be used to enter the edit mode. 

Example: 50 CLEAR <ret> 

(Clears screen 50 and makes it current.) 
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CLEARS ( serif #screens --- ) 

The CLEARS command is used to clear blocks of screens at a time. 
After user verification, it starts with the specified screen and clears 
the specified number of consecutive screens. The first screen cleared 
is made current so that the L command can be used to enter the edit mode. 

Example: 25 3 CLEARS <ret> 

Clear from SCR 25 

to SCR 27 <Y/N> Y 

(Screens 25-27 are cleared. Screen 25 is made current.) 


SMOVE ( from to #screens — ) 

The SMOVE command is a multiple screen copy command used for copying 
large numbers of consecutive screens at a time. User verification is 
required by this command to avoid disastrous loss of data. All screens 
to be copied are read into available memory and the user is prompted 
to initiate the copy. This allows the swapping of disks between moves 
to make disk transfers possible. The number of screens the SMOVE command 
can copy at a time is limited only by available memory. 

Example: 50 60 5 SMOVE <ret> 

SMOVE from 50 thru 54 

to 60 thru 64 <Y/N> Y 
Insert source <RETURN> <ret> 

Insert dest. <RETURN> <ret> 

(Transfers the specified screens.) 
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Editor Command Summary 

Below is a quick reference list of all the commands which the video editor 
recognizes. 


Entering the Edit Mode: (executed outside of the edit mode) 


V ( scr# — ) 

Enter the edit mode and view the 
specified screen. 


Re-view the current screen. 


WHERE ( — ) 

Enter the edit mode and position the 
cursor over the word that caused a 
compilation error. 


LOCATE cccc ( — ) 

Enter the edit mode and position the 
cursor over the word defining "cccc". 


LOCATOR ( ON/OFF — ) 

When ON, allows all words compiled until 
the next OFF to be locatable using the 
LOCATE command above. 


( #lines — ) 

Sets the length (in lines) of the storage 
buffer. The default is five. 


#BUFS 
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Cursor Movement: 
Ctrl a 

Ctrl v 

Ctrl < 

Ctrl > 

RETURN 


(issued within the edit mode) 

Move cursor up one line, wrapping to the bottom 
line if moved off the top. 

Move cursor down one line, wrapping to the top 
line if moved off the bottom. 

Move cursor left one character, wrapping to the 
right edge if moved off the left. 

Move cursor right one character, wrapping to the 
left edge if moved off the right. 

Position the cursor at the beginning of the next 
line. 


TAB 


Advance to next tabular column. 


Editing Commands: (issued within the edit mode) 


Ctrl 

INS 

Insert one blank at cursor location, losing the 
last character on the line. 

Ctrl 

DEL 

Delete character under cursor, closing the line. 

shift 

INS 

Insert blank line above current line, losing the 
last line on the screen. 

shift 

DEL 

Delete current cursor line, closing the screen. 

Ctrl 

I 

Toggle insert-mode/replace-mode, (see full 
description of ctrl-I). 

BACKS 


Delete last character typed, if on the same line 
as the cursor. 

Ctrl 

H 

Erase to end of line (Hack). 
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Buffer Management: (issued within the edit mode) 


Ctrl 

T 

Delete current cursor line sending it to the 
edit buffer for later use. 

Ctrl 

F 

Take the current buffer line and insert it 
above the current cursor line. 

Ctrl 

K 

Copy current cursor line sending it to the 
edit buffer for later use. 

Ctrl 

U 

Take the current buffer line and copy it to the 
current cursor line. 

Ctrl 

R 

Roll the buffer making the next buffer line 
current. 

Ctrl 

B 

Roll the buffer backwards making the previous 
buffer line on the screen current. 

Ctrl 

C 

Clear the current buffer line and perform 
a ctrl-B. 


Note: The current buffer line is last line visible on the video display. 


Changing Screens: 
Ctrl P 

Ctrl N 

Ctrl S 
Ctrl Q 

Special Keys: 

ESC 

Ctrl A 


(issued within the edit mode) 

Display the previous screen saving all changes 
made to the current text window. 

Display the next screen saving all changes made 
to the current text window. 

/ 

Save the changes made to the current text window 
and end the edit session. 

Quit the edit session forgetting all changes 
made to current text window. 

(issued within the edit mode) 

Do not interpret the next key typed as any of 
the commands above. Send it directly to the 
screen instead. 

Put "==>", or erase the lower right-hand 

corner of the text window. 


Ctrl J 

Ctrl 0 


Split the current line into two lines at the 
point where the cursor is. 

Corrects any major editing blunders. 
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Screen Management: 
FLUSH 


(executed outside of the edit mode) 


Save any updated FORTH screens to disk. 


( — ) 


EMPTY-BUFFERS 


Forget any changes made to any screens not 
yet FLUSHed to disk. Used in "losing" major 
editing mistakes. The abbreviation MTB is 
more commonly used. 


( — ) 


COPY 


Copies screen #from to screen #to. 


( from to — ) 


CLEAR 


( scr# 

Blank fills specified screen. This performs 
the same functions as "WIPE" in Leo Brodie's 
book. 


— ) 


CLEARS 


( scr# Iscreens 

Blank fills the specified number of screens 
starting with screen scr#. 


— ) 


SMOVE 


( from to #screens 

Duplicate the specified number of screens 
Starting with screen number "from". Allows 
swapping of disks before saving screens to 
screen number "to". 


— ) 
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STRING UTILITIES 


The following collection of words describes the string utilities of the 
valFORTH Utilities Package. Strings have been implemented in the FORTH 
language in many different ways. Most implementations set aside space for a 
third stack a string stack. As strings are entered, they are moved (using 
CMOVE) to this stack. When strings are manipulated on this stack, many long 
memory moves are usually required. This method is typically much slower than 
the method implemented in valFORTH. 

Rather than waste memory space with a third stack, valFORTH uses the 
already existing parameter stack. Unlike the implementation described above, 
valFORTH does not store strings on the stack. Rather, it stores the addresses 
of where the strings can be found.* Using this method, words such as SWAP , 
DUP , PICK , and ROLL can be used to manipulate strings. Routines such as 
string sorts which work on many strings at a time are typically much faster 
since addresses are manipulated rather than long strings. In practice, we 
have found few if any problems using this method of string representation. 


String Glossary 

For the purposes of this section, a string is defined to be a sequence 
of up to 255 characters preceded by a byte indicating its length. The first 
character of the string is referenced as character one. If the length of the 
string is zero, it has no characters and is called the "null" string. In 
stack notation, strings are represented by the symbol $ and the address of the 
string is stored on the stack rather than the string itself*. 


-TEXT addrl n addr2 -- flag 

The word -TEXT compares n characters ataddressl with n characters 
at address2. Returns a false flag if the sequences match, true if they 
don't. Flag is positive if the character sequence at addressl is alpha¬ 
betically greater than the one at address2. Flag is zero if the 
character sequences match, and is negative if the character sequence at 
addressl is alphabetically less than the one at address2. 

-NUMBER addr — d 

-NUMBER functions identically to the standard FORTH word NUMBER 
with the only difference being that -NUMBER does not abort program 
execution upon an illegal conversion. -NUMBER takes the character string 
at addr and attempts to convert it to a double number. On successful 
conversion, the value d is returned with the status variable NFLG set 
to one. On unsuccessful conversion, a double number zero is returned 
with the variable NFLG set to zero. -NUMBER is pronounced "not number". 


*Representing strings on the stack by their addresses is a very useful concept 
borrowed from MMS Forth (TRS-80), authored by Tom Dowling, and available from 
Miller Microcomputer Services, 617-653-6136. 
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NFLG 


— addr 

A variable used by -NUMBER that indicates whether the last conversion 
attempted was successful. NFLG is true if the conversion was successful; 
otherwise, it is false. 

UMOVE addrl addr2 n -- 

UMOVE is a "universal" memory move. It takes the block.of memory 
n bytes long at addrl and copies it to memory location addr2. UMOVE 
correctly uses either CMOVE or cCMOVE so that when a block of memory is 
moved onto part of itself, no data are destroyed. 

" cccc" — (at compile time) 

cccc: — addr (at run time) 

If compiling, the sequence cccc (delimited by the trailing ") is 
compiled into the dictionary as a string: 

I len | c | c I c !...I c i 

All valFORTH strings are represented in this fashion. Since a single 
byte is used to store the length, a maximum string length of 255 is 
allowed. A string with 0 length is called a "null" string. At 
execution time, " puts the address in memory where the string is 
located onto the stack. 

Note that " is IMMEDIATE. When executed outside of a colon 
definition, the string is not compiled into the dictionary, but 
is stored at PAD instead. 

Example: " This is a string" 

$C0NSTANT cccc $ — (at compile time) 

cccc: — $ (at execution time) 

Takes the string on top of the stack and compiles it into the 
dictionary with the name cccc. When cccc is later executed, the 
address of the string is pushed onto the stack. 

Example: " Ready? <Y/N> 11 SCQNSTANT VERIFY 

SVARIABLE cccc n - 
cccc: -- $ 

Reserves space for a string of length n. When cccc is later 
executed, the address of the string is pushed onto the stack. 

Example: 80 $VARIABLE TEXTLINE 

$. $ - 

Takes the string on top of the stack and sends it to the current 
output device. 

Example: " Hi there" $. <ret> Hi there 

$1 $ addr -- 

Takes the string at second on stack and stores it at the address 
on top of stack. 

Example: " Store me!" TEXTLINE $! 



$+ $1 $2 — $3 

Takes $2 and concatenates it with $1, leaving S3 at PAD. 

Example: " Santa " $C0NSTANT 1ST 

" Claus" SCONSTANT LAST 
1ST LAST $+ 

$. <ret> Santa Claus 

LEFTS $1 n — $2 

Returns the leftmost "n" characters of $1 as $2. $2 is stored 

at PAD. 

Example: " They" 3 LEFTS $. <ret> The 

RIGHTS $1 n — $2 

Returns the rightmost "n" characters of $1 as $2. $2 is stored 

at PAD. 

Example: " mother" 5 RIGHTS $. <ret> other 

MID$ $1 n u — $2 

Returns $2 of length u starting with the nth character of Si- 
Recall that the first character of a string is numbered as one. 

Example: " Timeout" 3 2 MID$ $. <ret> me 

LEN $ — Ten 

Returns the length of the specified string. 

ASC $ — c 

Returns the ASCII value of the first character of the specified 
string. 

SCOMPARE SI $2 — flag 

Compares $1 with $2 and returns a status flag. The flag is 

a) positive if $1 is greater than $2 or is equal to $2, but longer, 

b) zero if the strings match and are the same length, and c) negative 
if $1 less than $2 or if they are equal and $1 is shorter than $2. 

$= $1 $2 -- flag 

Compares two strings on top of the stack and returns a status 
flag. The flag is true if the strings match and are equal in length, 
otherwise it is false. 

$< $1 $2 -- flag 

Compares two strings on top of the stack and returns a status 
flag. The flag is true if $1 is less than $2 or if $1 matches $2 but 
is shorter in length. 

$> $1 $2 — flag 

Compares two strings on top of the stack and returns a status 
flag. The flag is true if $1 is greater than $2 or if $1 matches $2 
but is longer in length. 

SAVES $1 -- $2 

As most string operations leave resultant strings at PAD, the word 
SAVES is used to temporarily move strings to PAD+512 so that they can 
be manipulated without being altered in the process. 

Example: " Wash" SAVES " ington" $+ 
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INSTR 


$1 $2 — n 

Searches $1 for first occurrence of $2. Returns the character 
position in $1 if a match is found; otherwise, zero is returned. 

Example: " FDCBA" $C0NSTANT GRADES 

GRADES " A" INSTR 1- . <ret> 4 

CHR$ c — $ 

Takes the character "c" and makes it into a string of length one 
and stores it at PAD. 

DVAL $ - d 

Takes numerical string $ and converts it to a double length number. 
The variable NFLG is true if the conversion is successful, otherwise it 
is false. See -NUMBER above. 

Example: " 123" DVAL D. <ret> 123 


VAL $ - n 

Takes the numerical string $ and converts it to a single length 
number. The variable NFLG is true if the conversion is successful, 
otherwise it is false. See -NUMBER above. 

DSTR$ d — $ 

Takes the double number d and converts it to its ASCII representa¬ 
tion as $ at PAD. 

Example: 123 DSTR$ $. <ret> 123 

STR$ n - $ 

Takes the single length number n and converts it to its ASCII 
representation as $ at PAD. 

STRINGS n $1 - $2 

Creates $2 as n copies of the first character of $1. 

#IN$ n - $ 

#IN$ has three similar but different functions. If n is positive, 
it accepts a string of n or fewer characters from the terminal. If n is 
zero, it accepts up to 255 characters from the terminal. If n is nega¬ 
tive, it returns only after accepting -n characters from the terminal. 
The resultant string is stored at PAD. 

IN$ - $ 

Accepts a string of up to 255 characters from the terminal. 

S-TB $1 — $2 

Removes trailing blanks from $1 leaving new $2. 

SXCHG $1 - $2 

Exchanges the contents of $1 with $2. 
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ARRAYS and their COUSINS 


All of the words described below create structures that are accessed in the 
same way, i.e., by putting the index or indices on the stack and then typing 
the structure's name. The differences are in the ways the structures are 
created. 

The concept of the array should be known from BASIC. While in fig-FORTH 
there is no standard way to implement arrays and similar structures, there 
does exist a general consensus about how this should be done. 

The point on which there is the most divergence of opinion is whether the 
first element in an array should be referred to by the index 0 or 1. We 
select 0 for the first index since this gives much cleaner code and makes 
more sense than 1 after you get used to it. (We've worked with it both ways.) 

ARRAY and CARRAY, and 2ARRAY and 2CARRAY 

The size of an array, specified when it is defined, is the number of elements 
in the array. In other words, an array defined by 

8 ARRAY BINGO 

will have 8 elements numbered 0-7. 

To access an element of an array, do 
n array-name 

to get the address of the nth element on the stack. (You will not be told 
if the number n is not a legitimate index number for the array.) For example, 

5 BINGO 

will leave the address of element number 5 in BINGO on the stack. You can 
store to or fetch from this address as you require. 

The word CARRAY defines a byte or character array. A c-array works the same 
as an array, except that you must use C@ and C! to manipulate single elements, 
rather than @ and !. 

The words 2ARRAY and 2CARRAY each take two numbers during definition of a 
2ARRAY or 2CARRAY, and 2ARRAYS and 2CARRAYS take two numbers to access an 
element. Note that when using a 2CARRAY named, say, CHESSBOARD, and a constant 
named ROOK, the two phrases 

ROOK 4 6 CHESSBOARD C! 

and 

ROOK 6 4 CHESSBOARD C! 

don't do the same thing. Also note that the phrase 
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8 8 2CARRAY CHESSBOARD 


defines a 2CARRAY of 8 x 8 = 64 elements, with both indices running from 0 to 

7. 

When an ARRAY or a CARRAY is defined, the initial values of the elements 
are undefined. 

TABLE AND CTABLE 

A cousin of ARRAY is TABLE. Example: The phrase 
TABLE THISLIST 14 , 18 , -34 , 16 , 

defines a table THISLIST of 4 elements. (The commas above are part of the 
code and must be included.) The number of elements does not have to be 
specified. The elements in THISLIST are accessed using the indices 0-3, 
the same as if it had been defined as an array. The word CTABLE works 
similarly, though using C, instead of , to compile in the numbers. Note that 
negatives won't be compiled in by a C, since in two's complement representation 
negative numbers always occupy the maximum number of bytes. 

VECTOR and CVECTOR 

The last array-type words in this package are CVECTOR and VECTOR. Vector is 
just another name for a list. These words are used when the elements of the 
array you want to create are on the stack, with the last element on top of the 
stack. You just put the number of elements on the stack and the VECTOR or 
CVECTOR, and the name you want to use. Example: 

-3 8 127 899 -43 5 VECTOR POSITIONS 

creates an array named POSITIONS with 5 elements 0-4 with -3 in element 0 
and -43 in element 4. CVECTOR works in a similar way. 


EXAMPLES: 


2 3 BINGO ! 

Stores the value 2 into element 3 of array BINGO. 


2 THISLIST @ 

Will leave the value in element 2 of table THISLIST. 
According to the definition of THISLIST above, this value 
will be -34. 


3 POSITION @ . <cr> 899 
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ARRAY WORD GLOSSARY 


ARRAY cccc, n -- (compiling) 

cccc: m — addr (executing) 

When compiling, creates an array named cccc with n 16-bit elements numbered 0 
thru n-1. Initial values are undefined. When executing, takes an argument, 
m, off the stack and leaves the address of element m of the array. 

CARRAY cccc, n -- (compiling) 

cccc: m -- addr (executing) 

When compiling, creates a c-array named cccc with n 8-bit elements numbered 
0 thru n-1. Initial values are undefined. When executing, takes an argument, 
m, off the stack and leaves the address of element m of the c-array. 

TABLE cccc, -- (compiling) 
cccc: m -- addr (executing) 

When compiling, creates a table named cccc but does not allot space. Elements 
are compiled in directly with , (comma). When executing, takes one argument, 
m off the stack and, assuming 16-bit elements, leaves the address of element 
m of the table. 


CTABLE cccc, 
cccc: 

When compiling, 
are compiled in 
m off the stack 
of the c-table. 


(compiling) 
m -- addr (executing) 

creates a c-table named cccc but does not allot space. Elements 
directly with C, (c-comma). When executing, takes one argument, 
and, assuming 8-bit elements, leaves the address of element m 


X! nO ... nN count addr -- 

Stores count 16-bit words, nO thru nN into memory starting at addr, with nO 
going into addr. Pronounced "extended store." 

XC! bO ... bN count addr ~~ 

Stores count 8-bit words, bO thru bN into memory starting at addr, with bO 
going into addr. Pronounced "extended c-store." 


VECTOR cccc, nO ... nN count — (compiling) 

cccc: m -- addr (executing) 

When compiling, creates a vector named cccc with count 16-bit elements 
numbered 0-N. nO is the initial value of element 0, nN is the initial value 
of element N, and so on. When executing, takes one argument, m, off the stack 
and leaves the address of element m on the stack. 


CVECTOR cccc, bO ... bN count -- (compiling) 
cccc: m -- addr (executing) 

When compiling, creates a c-vector named cccc with count 8-bit elements 
numbered 0-N. bO is the initial value of element 0, bN is the initial value 
of element N, and so on. When executing, takes an argument, m, off the stack 
and leaves the address of element m on the stack. 
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CASE STRUCTURES 


It often becomes necessary to make many tests upon a single number. 
Typically, this is accomplished by using a series of nested "DUP test IF" 
statements followed by a series of ENDIFs to terminate the IFs. This is 
arduous and very wasteful of memory, valFORTH contains four very .powerful 
Paseal-type CASE statements which ease programming and conserve memory. 


The CASE: structure 


Format: 


CASE: wordname 
wordO 
wordl 

wordN ; 


The word CASE: creates words that expect a number from 0 to 
N on the stack. If the number is zero, wordO is executed; if the 
number is one, the wordl is executed; and so on. No error checks are 
made to ensure that the case number is a legal value. 

Example: 


: ZERO ." Zero" ; 

: ONE ." One" ; 

: TWO ." Two" ; 

CASE: NUM 
ZERO 
ONE 

TWO ; 

0 NUM <ret> Zero 

1 NUM <ret> One 

2 NUM <ret> Two 

Note that any other number (e.g. 3 NUM) will crash the system. 
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The CASE Structure 


Format: 


: wordname 

CASE 

wordO 

wordl 

wordN 

( NOCASE wordnone ) (optional) 

CASEND 


The CASE...CASEND structure is always used within a colon 
definition. Like CASE: above, it requires a number from 
0 and N. However, unlike CASE; above* boundary checks are made 
so that an illegal case will do nothing. If the optional NOCASE 
clause is included then wordnone is executed if an "out of bounds" 
number is used. 

Examples: 

I) : ZERO Zero" ; 

. : ONE ." One" ; 

: TWO Two" ; 

: CHECKNUM ( n — ) 

CASE 

ZERO 

ONE 

TWO 

CASEND ; 

0 CHECKNUM <ret> Zero 

1 CHECKNUM <ret> One 

999 CHECKNUM <ret> (nothing happens) 

2 CHECKNUM <ret> Two 
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: GRADEA 

A" ; 

: GRADEB 

B" ; 

: GRADEC 

C" ; 

: GRADED 

D” ; 

: OTHER 

Failed" 


DECIMAL 

: GETGRADE ( - ) 

KEY 65 - (Convert A to 0, B to 1, etc) 

CASE 
GRADEA 
GRADEB 
GRADEC 
GRADED 

NOCASE OTHER 
CASEND ; 


GETGRADE <return and press A> A 
GETGRADE creturn and press B> B 
GETGRADE <return and press F> Failed 
GETGRADE creturn and press D> D 


The SEL Structure 


Format: 

: wordname 

SEL - (Select) 

nl -> wordO 
n2 -> wordl 

nN > wordN 

( NOSEL wordnone ) (optional) 

SELEND 






The SEI-SELEND structure is used when the "selection" numbers 

(nl etc.) are not sequential. This structure is somewhat slower than 
either CASE or CASE: , but is much more general. SEL is typically 
used in operations such as table driver menus where single keystroke 
commands are used. The valFORTH video editor uses the SEL structure 
to implement the many editing keystroke commands. 


Example: 


I) 


NICKEL 

nickel." ; 

DIME 

." dime." ; 

QUARTER 

." quarter." ; 

4BITS 

." fifty cent piece." 

SUSANB 

dollar" ; 

BAD$$$ 

." wooden nickel." ; 


: MONEY-NAME ( n — ) 

." That is called a " 

SEL 

5 -> NICKEL 
10 -> DIME 
25 -> QUARTER 
50 -> 4BITS 
100 ~> SUSANB 

NOSEL BAD$$$ ( this line is optional ) 

SELEND ; 


5 MONEY-NAME <ret> That is called a nickel. 

33 MONEY-NAME <ret> That is called a wooden nickel. 

25 MONEY-NAME <ret> That is called a quarter. 


The COND Structure 


Format: 


wordname 




COND 

conditionO 

« 

wordsO 

» 

condition1 

« 

wordsl 

» 

conditionN 

« 

wordsn 

» 


( NOCOND wordsnone ) (optional) 

CONDEND 

• • * 3 


XII-11 





Unlike the three previous CASE structures which test for equality, 
the COND structure bases its selection upon any true conditional test 
(e.g. if n > 0 then...) COND can also be used for range cases. The 
NOCOND clause is optional and is only executed if no other condition 
passes. Only the code of the first condition that passes will be 
executed. 

Example: 

: EXAM ( score -- grade ) 

COND 


90 

>= 

« 

." Grade 

of A" 

4 

» 

80 

>= 

« 

." Grade 

of B" 

3 

» 

70 

>= 

« 

." Grade 

of C" 

2 

» 

60 

>= 

« 

Grade 

of D" 

1 

» 

NOCOND 

1! 

Not 

too good" 

0 




CONDEND ; 

Note that neither « nor » are needed (nor allowed) around the 
"NOCOND" case. Also note that more than one word can be executed 
between the « and » . 




DOUBLE NUMBER EXTENSIONS 


The following words extend the set of double number words to be as nearly 
identical as possible to the set in the book Starting FORTH . The exceptions 
are DVARIABLE and DCONSTANT which conform to the FIG standard by expecting 
initial values on the stack. 

All of the single number operations comparable to the double number operations 
below were machine coded; all of the words below (with the exception of DVARIABLE) 
have high-level run time code and so are considerably slower than their single 
number counterparts. 


DOUBLE NUMBER EXTENSION GLOSSARY 

DVARIABLE cccc d — 

cccc: -- addr 

At compile time, creates a double number variable cccc with the initial value d. 
At run time, cccc leaves the address of its value on the stack. 

DCONSTANT cccc d — 

cccc: -- d 

At compile time, creates a double number constant cccc with the initial value d. 
At run time, cccc leaves the value d on the stack. 

0 . — 0 . 

A double number constant equal to double number zero. 

1 . — 1 . 

A double number constant equal to double number one. 

D- dl d2 — d3 

Leaves dl-d2=d3. 

D0= d — flag 

If d is equal to 0. leaves true flag; otherwise, leaves false flag. 

D= dl d2 - flag 

If dl equals d2, leaves true flag; otherwise, leaves false flag. 

D0< d -- flag 

If d is negative, leaves true flag; otherwise, leaves false flag. 

D< dl d2 — flag 

If dl is less than d2, leaves true flag; otherwise, leaves false flag. 

D> dl d2 -- flag 

If dl is greater than d2, leaves true flag; otherwise, leaves false flag. 
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DMIN dl d2 — d3 

Leaves the minimum of dl and d2. 

DMAX dl d2 — d3 

Leaves the maximum of dl and d2. 

D>R d — 

Sends the double number at top of stack to the return stack. 

DR> — d 

Pulls the double number at top of the return stack to the stack. 

D, d — 

Compiles the double number at top of stack into the dictionary. 

DU< udl ud2 -- flag 

If the unsigned double number udl is less than the unsigned double number ud2, 
leaves a true flag; otherwise, leaves a false flag. 

M+ dl n -- d2 

Converts n to a double number and then sums with dl. 


XI I-15 




HIGH RESOLUTION TEXT OUTPUT 


Occasionally, the need arises to print text in high resolution graphic 
displays (8 GR.). The following set of words explains how Graphic Characters 
can be used in valFORTH programs. The Graphic-Character output routines are 
designed to function identically to the standard FORTH output operations. 
There is an invisible cursor on the high resolution page which always points 
to where the next graphic-character will be printed. As with normal text 
output, this cursor can be repositioned at any time and in various ways. 
Because of the nature of hi-res printing, this cursor can also be moved 
vertically by partial characters. This allows for super/subscripting, over¬ 
striking, and underlining. Multiple character fonts on the same line are 
also possible. 


GCINIT 

Initializes the graphic character output routines. This must be 
executed prior to using any other hi-res output words. 

GC. n -- 

Displays the single length number n at the current hi-res cursor 
location. 


GC.R nl n2 — 

Displays the single length number nl right-justified in a field 
n2 .graphic characters wide. See .R . 

GCD.R d n ~ 

Displays the double length number d right-justified in a field n 
graphic characters wide. See D.R . 

GCEMIT c — 

Displays the text character c at the current hi-res cursor location. 
Three special characters are interpreted by GCEMIT . The up arrow (t) 
forces text output into the superscript mode; the down arrow {$) forces 
the text into the subscript mode; and the left arrow (<-) performs a 
GCBKS command (described below). See OSTRIKE below; also see EMIT. 

GCLEN addr n -- len 

Scans the first n characters at addr and returns the number of 
characters that will actually be displayed on screen. This is typically 
used to find the true length of a string that contains any of the non¬ 
printing special characters described in GCEMIT above. Used principally 
to aid in centering text, etc. 


GCR 

Repositions the hi-res cursor to the beginning of the next hi-res 
text line. See CR . 

GCLS 

Clears the hi-res display and repositions the cursor in the upper 
lefthand corner. 
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GCSPACE 


Sends a space to the graphic character output routine. See SPACE . 

GCSPACES n — 

Sends n spaces to the graphic character output routine. See SPACES . 

GCTYPE addr n — 

Sends the first n characters at addr to the graphic character output 
routine. See TYPE . 

GC" cccc" 

Sends the character string cccc (delimited by ") to the graphic 
character output routine. If in the execution mode, this action is 
taken immediately. If in the compile mode, the character string is 
compiled into the dictionary and printed out only when executed in 
the word that uses it. See ." . 


GCBKS 

Moves the hi-res cursor back one character position for overstriking 
or underlining. 

GCPOS horz vert — 

Positions the hi-res cursor to the coordinates specified. Note 
that the upper lefthand corner is 0,0. 

GC$. addr — 

Sends the string found at addr and preceded by a count byte to the 
graphic character output routine. See $. . 

SUPER 

Forces the graphic character output routine into the superscript 
mode (or out of the subscript mode). See VMI below. May be performed 
within a string by the ^ character. 

SUB 

Forces the graphic character output routine into the subscript 
mode (or out of the superscript mode). See VMI below. May be performed 
within a string by the * character. 

VMI n — 

Each character is eight bytes tall. The VMI command sets the number 
of eighths of characters to scroll up or down when either a SUPER or SUB 
command is issued. Normally, 4 VMI is used to scroll.4/8 or half a 
character in either direction. 

VMI# - addr 

A variable set -by VMI. 

OSTRIKE ON or OFF — 

The GCEMIT command has two separate functions. If OSTRIKE (overstrike) 
option is OFF, the character output will replace the character at the 
current cursor position. This is the normal method of output. If the 
OSTRIKE option is ON, the new character is printed over top of the previous 
character giving the impression of an overstrike. This allows the user to 
underline text and create new characters: Example: To do underline, a 
value of, say, 2 should be used with VMI, and then the * character added 
in the string before the underline character. 
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GCBAS 


— addr 

A variable which contains the address of the character set displayed 
by GCEMIT. To change character sets, simply store the address of your 
new character set into this variable. 

GCLFT -- addr 

A variable which holds the column position of the left margin. 
Normally two, this can be changed to obtain a different display window. 

GCRGT - addr 

A variable which holds the column position of the right margin. 
Normally 39, this can be changed to obtain a different display window. 
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MISCELLANEOUS UTILITIES 


This is a grab-bag of useful words. Here they are... 


XR/W #secs addr blk flag -- 

"Extended read-write." The same as R/W except that XR/W accepts a sector 
count for multiple sector reads and writes. Starting at address addr and 
block blk, read (flag true) or write (flag false) #secs sectors from or to 
disk. 

SMOVE org des count — 

Move count screens from screen # org to screen # dest. 

The primary disk rearranging word, also used for moving sequences of screens 
between disks. This is a smart routine that uses all memory available below 
the current GR.-generated display list, with prompts for verification and 
disk swap if desired. See valFORTH Editor 1.1 documentation for further details 

LOADS start count -- 

Loads count screens starting from screen # start. This word is used if you 
want to use words that are not chained together by —> ‘s. It will stop 
loading if a CONSOLE button is held down when the routine finishes loading 
its present screen. 

THRU start finish -- start count 

Converts two range numbers to a start-count format. Example: 

120 130 THRU PLISTS 
will print screens 120 thru 130. 

SEC n — 

Provides an n second delay. Uses a tuned do-loop. 

MSEC n — 

Provides an n millisecond delay, (approx) 

Uses a tuned do-loop. 

H->L n — b 

Moves the high byte of n to the low byte and zero's the high byte, creating 
b. Machine code. 

L->H nl -- n2 

Moves the low byte of nl to the high byte and zero's the low byte, creating 
n2. Machine code. 

H/L nl -- nTfhil_ nl(loJ. 

Split top of stack into two stack items: New top of stack is low byte of old 
top of stack. New second on stack is old top of stack with low byte zeroed. 
Example: HEX 1234 H/L .S <cr> 1200 0034 


XI11-5 



ft 


BIT b — n 

Creates a number n that has only its bth bit set. The bits are numbered 0-15, 
with zero the least significant. Machine code. 

?BIT n b — f 

Leaves a true flag if the bth bit of n is set. Otherwise leaves a false flag. 
TBIT nl b — n2 

Toggles the bth bit of nl, making n2. 

SBIT nl b — n2 

Sets the bth bit of nl, making n2. 

RBIT nl b — n2 

Resets the bth bit of nl, making n2. 

STICK n -- horiz vert 

Reads the nth stick (0-3) and resolves the setting into horizontal and 
vertical parts, with values from -1 to +1. -l -l means up and to the left, 

PADDLE nl — n2 

Reads the nlth paddle (0-7) and returns its value n2. Machine code. 

ATTRACT f — 

If the flag is true, the attract mode is initiated. If the flag is false, 
the attract mode is terminated. 

NXTATR — 

If the system is in the attract mode, this command cycles to the next color 
setup in the attract sequence. Disturbs the timer looked at by 16TIME. 

HLDATR — 

If the system is in attract mode, zero's fast byte of the system timer so 
that attract won't cycle to next color setup for at least four seconds 
or until system timer is changed, say by NXTATR. Disturbs the timer looked 
at by 16TIME. 

16TIME — n 

Returns a 16 bit timer reading from the system clock at locations 19 and 20, 
decimal. This clock is updated 60 times per second, with the fast byte in 
20. Machine code, not fooled by carry. 

8RND — b 

Leaves one random byte from the internal hardware. Machine code. 

16RND — n 

Leaves one random word from the internal hardware. Machine code with 20 
cycle extra delay for rerandomization. 

CHOOSE ul — u2 

Randomly choose an unsigned number u2 which is less than ul. 
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CSHUFL addr n — 

Randomly rearrange n bytes in memory, starting at address addr. 

Pronounced "c-shuffle." 

SHUFL addr n — 

Randomly rearrange n words in memory, starting at address addr. Pronounced 
"shuffle." SHUFL may also be used to shuffle items directly on the stack by 
doing SP@ n SHUFL. 


H, n — 

See DEBUG Glossary. 


A. addr — 

Print the ASCII character at addr, or if not printable, print a period. 
(Used by DUMP). 


DUMP addr n -- 

Starting at addr, dump at least n bytes (even multiple of 8) as ASCII and 
hex. May be exited early by pressing a CONSOLE button. 

BLKOP system use only 

BXOR addr count b -- 

Starting at address addr, for .count bytes, perform bit-wise exclusive or 
with byte b at each address. Useful for toggling an area of display memory 
to inverse video or a different color, and for other purposes. For instance, 
in 0 GR., do 


DCX 88 @ 280 128 BXOR 

Then do Shift-Clear to clear the screen. Pronounced "block ex or." 


BAND addr count b -- 

Starting at address addr, for count bytes, perform bit-wise AND with byte b 
at each address. Applications similar to BXOR. 

Pronounced "block and." 

BOR addr count b - 

Starting at address addr, for count bytes, perform bit-wise or with byte b 
at each address. Applications similar to BXOR. 

Pronounced "block or." 

STRIG n — flag 

Reads the button of joystick n (0-3). Leaves a true flag if the button is 
pressed, a false flag if it isn't, 

PTRIG n — flag 

Reads the button of paddle n (0-7). Leaves a true flag if the button is 
pressed, a false flag if it isn't. 
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TRANSIENTS 


One of the more annoying parts about common releases of FORTH concerns the 
FORTH machine code assemblers. On the positive side, FORTH-based assemblers 
can be extraordinarily smart and easy to use interactively, and can compile 
on the fly as you type, rather than in multiple-pass fashion. (The 6502 
assembler provided with valFORTH is a good example of a smart, structured, 
FORTH-based assembler.) On the other hand, since the assembler loads into 
the dictonary one usually sacrifices between 3 and 4K of memory on a utility 
that is only a compilation aid, and is not used during execution. With the 
utility described below, however, you can use the assembler and then remove 
it from the dictionary when you're finished with it. 

In the directory of the Utilities/Editor disk (screen 170) you will find a 
heading of Transients. Loading this screen brings in three words: TRANSIENT, 
PERMANENT, and DISPOSE, and a few variables. It also defines a new area of 
memory called the Transient area. This area is used to load utilities like 
the assembler, certain parts of case statements, and similar constructs, that 
have one characteristic in common: They have compile-time behavior only, and 
are not used at run-time. An example will help make clear the sequence of 
operations. You may recall that on the valFORTH disk, in order to load float¬ 
ing point words you needed the assembler. Let's make a disk that has floating 
point but no assembler: 

* Boot your valFORTH disk. It can be the bare system, or your normal program¬ 
ing disk if it doesn't have the assembler already in it. 

* Insert your Utilities/Editor disk, find the Transient section in the 
directory, and load it. 

* Do MTB (EMPTY-BUFFERS) and swap in your valFORTH disk. (It is a VERY good 

idea to get into the habit of doing MTB before swapping disks.) Find the 
assembler in the directory, but before you load it, do TRANSIENT to cause it 

to be loaded into the transient dictionary area, in high memory. Now go ahead 

and load the assembler. When it is loaded, do PERMANENT so that the next 
entries will go into the permanent dictionary area, which is back where you 
started. 

* Now find and load the floating point words. 

* Finally, do DISPOSE to pinch off the links that tie the transient area 

(with the assembler in it) to the permanent dictionary, with the floating 
point words in it. Do a VLIST or two to prove it to yourself. (Note that 
there are about a half-dozen words in the assembler vocabulary in the kernel. 
These were in the dictionary on boot up and are not affected by DISPOSE.) 

You can derive great benefit from the simple recipe above, and if you study 
the Transient code a bit, you may learn even more. We offer several comments: 



* In the ca se of the above recipe, you didn't actually have to do PERMANENT 
and TRANSIENT because the assembler source code checks at the front to see if 
TRANSIENT exists, and does it if so. At the end if checks to see if PERMANENT 
exists, and does it if so. -This conditional execution is accomplished with 
the valFORTH construct 

'(■)() 

which is described in valFORTH documentation. Take a look at the assembler 
source code to see how this is done. 

* If you want to do assembly on more than one section of code, you needn't 
DISPOSE until you really finished with the assembler; or, if you have DISPOSED 
of the assembler, you can bring it back in later without harm, by the same 
method. You can also code high-level definitions, and then more assembly 
code, and so on, and only do DISPOSE when you were finished. Be sure to do 
DISPOSE before SAVE or AUTO, however, because either your system will crash 

or your SAVE'd or AUTO'd program won't work. 

The situation is slightly different with "case" words, since if you bring 
them in more than once you'll get duplicate names on the run-time words like 
(SEL), (CASE) and CASE:, which uses extra space and defeats the purpose of 
Transients. 

* If you use the Transient structures for otherpurposes, remember only to 

send code that is not used at run-time to the transient area. As an example 
of this distinction, look at the code for the "case" words on the valFORTH 
disk. Note that the '( )( ) construct is again used, but that some of 

the parts of the case constructs, for instance (SEL), stay in the permanent 
dictionary. That is because (SEL) actually ends up in the compiled code, 
while SEL does not. 

* Look at the beginning of the code for the Transient structures, and notice 
that the Transient area has been set up 4000 bytes below the display list. 

(The byte just below the display list fn normal modes is pointed to by memory 
location 741 decimal, courtesy of the Atari OS.) This is usually a good place 
if only the 0 Graphics mode is used. (8 GR., for example, will over-write 
this area, crashing the system.) After DISPOSE is executed, this area is 
freed for other purposes. If you want to use a different area for Transients, 
just substitute your address into the source code on the appropriate screen. 
Remember that you must leave enough room for whatever will go into the Transient 
dictionary, and that NOTHING else must write to the area until you have cleared 
it out with DISPOSE. (This includes SMOVE, DISKC0PY1, DISKC0PY2, etc.) 

****** NOTE ***** NOTE ***** NOTE ***** NOTE ***** NOTE ****** 

In the above example, 4000 bytes have been set aside for the Transient area 
just below the 0 GR. display list. This amount of memory will generally hold 
the assembler and some case statement compiling words. REMEMBER that if you 
have relocated the buffers (see the section on Relocating Buffers) to this 
area as well, you will have a collision, and a crashed system in short order. 

To cure this, simply locate the Transient area 2113 bytes lower in memory so 
that there will be no overlap. 

****** NOTE ***** NOTE ***** NOTE ***** NOTE ***** NOTE ****** 
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C8 C, D0 

c, 

D3 

c. 

E6 C, 

C7 C, 

4 

COND 



4 

E6 C, C5 

C, 

4C 

C, 

5 

C; 

5 

89 = <( 1 1 
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4 
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4 
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5 
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5 
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6 
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END IF 
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0 ( Case statements: SEL ) 

1 

£ ’ ( PERMANENT PERMANENT ) < ) 

3 : (SEL) 

4 R 1+ DUP £+ DUP R C@ 

5 £* £* + R> DROP DUP >R SWAP 

6 DO I @ 3 PICK = 

7 IF I £+ SWAP DROP LEAVE 

8 ENDIF 

9 4 /LOOP SWAP DROP @EX ; 

10 

11 M TRANSIENT TRANSIENT )< ) 

1£ : SEL ?COMP 

13 7LOADINS COMPILE (SEL) HERE 

14 0 C, COMPILE NOOP [COMPILE! [ 

15 8 ; IMMEDIATE ==> 
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£ ’ ( PERMANENT PERMANENT ) ( ) 

3 : (CASE) 

4 R C@ MIN -1 MAX £* 

5 R 3 + + @EX 

6 R C@ £* 5 + R> + >R ; 
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3 

4 : CONDEND 

5 0 DO 

6 [COMPILE] ENDIF 

7 LOOP ; IMMEDIATE 

8 

9 ’ < PERMANENT PERMANENT )< ) 

10 
11 
i£ 

13 

14 _ 

15 


Screen: 64 

0 ( ValFORTH Video editor 
1 

£ BASE & DCX 

3 

4 ’( XC! )( £1 KLOAD ) 

5 1 < HIDCHR )( £4 KLOAD ) 

6 M > BSCD ) ( £6 KLOAD ) 

7 

8 
9 

10 
1 1 
1£ 

13 

14 

-> 15 


Screen: 6£ 

0 ( Case statements: CASE: 

1 

£ : CASE: 

3 <BUILDS 

4 SMUDGE !CSP 

5 [COMPILE] ] 

6 DOES) 

7 SWAP £* + 0EX ; 

8 
9 

10 
11 
1£ 

13 

14 

15 BASE ! 


Screen: 65 

0 ( ValFORTH Video editor 
1 
£ 

3 

4 

5 

6 
7 

a 

9 

10 

11 

IS 

1 vi 

14 

15 


VI. 1 ) 


==> 


VI. 1 > 



VI. 1 ) 


Screen: 66 

0 ( ValFORTH Video editor 
1 

£ VOCABULARY EDITOR IMMEDIATE 


Screen 
0 ( 


( X coord. 


3 EDITOR DEFINITIONS 

4 


5 

0 

VARIABLE 

XLOC 

6 

0 

VARIABLE 

YLOC 

7 

0 
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VARIABLE 

TBLK 


13 

14 

15 


( 

Y coord. 
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3 

4 

ARRAY UPSTAT ( update map 
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15 CONSTANT 15 
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1 - DUP 0< 

< 
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32 CONSTANT 32 
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( 
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6 


128 CONSTANT 128 
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7 

5 
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m 
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10 
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m 
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1+ DUP 31 > 

( 

AT R-SIDE?) 
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» 

m 
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( 
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m 
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8 CSHOW DNCUR ; 

9 

10 : CLREOL 

11 CBLANK !SCR 

12 1 LNFLG ! CURLOC 

13 32 XLOC © - 

14 ERASE CSHOW 

15 EDMRK ; 


< — ) 


< — ) 

< CLEAR ) 

< TO END ) 

< OF LINE) 



Screen: 72 

0 ( ValFORTH Video editor VI.1 ) 
1 

2 : HMCUR ( — ) 

3 CBLANK 0 XLOC ! 

4 0 YLDC ! CSHOW ; 


6 : BYTINS CBLANK 


( 


Screen: 75 

0 ( ValFORTH Video editor 


2 : LNDEL 

3 

4 


CBLflNK 3 LNFLG ! !SCR 
4 YLOC 0 4 / 

DO 1 I UPSTflT ! LOOP 
YLOC 0 15 < 


7 

XLOC 0 31 < 

( SPREAD LN ) 


7 

IF BOL 

8 

IF 



8 

DUP 32 + SWAP 

9 

CURLOC DUP 1+ 

( FROM, TO ) 


9 

15 YLOC 0 - 32 

10 

31 XLOC 0 - 

( # CHARS ) 


10 

CMOVE 

11 

<CMOVE 

( MOVE IT ) 


11 

ENDIF 

12 

END IF 



12 

BOL 15 YLOC 0 - 

13 

0 CURLOC C! 

( CLEAR OLD ) 


13 

32 * + 32 ERASE 

14 

CSHOW EDMRK ; 

( CHARACTER ) 

/ 

14 

CSHOW EDMRK ; 

15 


==> 


15 



Screen: 73 

0 ( ValFORTH Video editor 
1 

2 : BYTDEL 

3 CBLftNK 

4 XLOC 0 31 < 

5 IF 

CURLOC DUP 
1+ SWAP 
31 XLOC 0 - 
CMOVE 
END IF 
0 CURLOC 
31 XLOC 0 - + Ci 
CSHOW EDMRK : 


6 

7 

8 
9 

10 

11 

12 

13 

14 

15 


VI. 1 ) 


( — ) 
< CLOSE LINE) 


< FROM flDDR ) 
( TO flDDR ) 

< # CHARS ) 

< MOVE IT ) 


( BLANK OUT ) 
( CHAR AT ) 

( END OF LN ) 

— > 


Screen: 76 

0 < ValFORTH Video editor 
1 

2 : BFSHW 

3 PBLL 128 - < 

4 SBL 160 CMOVE ; ( 

5 

6 : BFROT 

7 PBL DUP 

8 BLEN + LMOVE 

9 PBL DUP 32 + 

10 SWAP BLEN 32 - 

11 CMOVE PBLL 32 + 

12 PBLL LMOVE 

13 BFSHW ; 

14 

15 


Screen: 74 

0 ( ValFORTH Video editor 
1 

2 : LNINS 

3 CBLflNK 2 LNFLG ! !SCR 

4 4 YLOC 04/ 
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m 
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• 

m 
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7 
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7 




8 

IF 
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EXIT 
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10 
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Placement of Tabs for valFORTH 1.1 Documentation 

The tab titles included should be cut apart and inserted into the tabs 
in the following order, starting at the highest position: 

* fig EDITOR Locate before section II 

*1.1 EXTENSIONS Locate before section IV 

*1.1 GLOSSARY Locate before section V 

* ASSEMBLER Locate before section VI 




Notes on Starting FORTH for the fig-Forth User 


April, 1982 


A very popular book on the FORTH language called Starting FORTH has recently 
been published. The author, Leo Brodie, gives an excellent description of the FORTH 
language as implemented at FORTH, Inc. fig-FORTH differs from that implementation 
in some areas, and this document explains those differences. All comments that 
apply to fig-FORTH also apply to valForth. 


BLANK = BLANKS (page 285) 

Brodie describes the word BLANK. In fig-FQRTH, this word is BLANKS. 

EMPTY-BUFFERS vs. EMPTY-BUFFERS (page 283) 

Brodie's word EMPTY-BUFFERS does not necessarily change the buffers. In fig- 
FORTH, EMPTY-BUFFERS zero fills the buffers. 

CONTEXT vs. CONTEXT (page 247) 

These two words are not synonymous in the two versions. fig-FORTH uses a 
system of VOC-LINKS with CONTEXT, while FORTH, Inc. does not. ‘ 

EXIT = ;S (page 246) 

The word EXIT, as Brodie describes it, is identical in function to ;$ in fig- 
FORTH. y 

'S = SP@ (page 247) 

The word 'S in FORTH, Inc.'s is SP@ in fig-FORTH. 

EMPTY (page 84) 

Not yet implemented in fig-FORTH. 

WIPE vs. CLEAR (page 84) 

CLEAR requires a screen number while WIPE clears the last screen edited. 
ABORT" (page 103) 

Not implemented in fig-FORTH. 


PROVIDED THROUGH THE COURTESY OF VALPAR INTERNATIONAL CORPORATION; 3801 East 34th Street, 
Suite 105; Tucson, Arizona. Further distribution of this public domain document must in¬ 
clude this notice. 


?DUP = -DUP (page 103) 

The word ?DUP in FORTH, Inc.'s is -DUP in fig-FORTH. 

?STACK vs. ?STACK (page 103) 

?STACK as described by Brodie as incorrect for fig-FORTH. ?STACK in fig- 
FORTH automatically aborts if there is a stack error. 

NEGATE = MINUS, DNEGATE = DMINUS (pages 123, 178) 

The words NEGATE and DNEGATE in FORTH, Inc.'s are MINUS and DMINUS respectively 
in fig-FORTH. 

+L00P vs. +L00P (page 143) 

The word +L00P, as Brodie describes it, works differently for negative stepping 
than the +L00P in fig-FORTH. fig-FORTH always ends if the index equals the limit, 
even for negative stepping. 


PAGE = CLS (page 143) 

Brodie's PAGE is called CLS in ValForth. It has no equivalent in fig-FORTH. 


U/MOD = U/ (page 177) 

Brodie's U/MOD is U/ in fig-FORTH. 


CREATE vs. CREATE (page 209) 

Brodie's CREATE works differently from CREATE in fig-FORTH. A word using CREATE 
in fig-FORTH must unSMUDGE the header before the word can be used. The unsmudges 
headers automatically. In addition, Brodie's CREATE and fig-FORTH CREATE move different 
default values in the CFA of the created header (see below). 


CREATE = <BUILDS (page 209) 

In Brodie's chapter 11 on extending the compiler, he uses the series CREATE... 
D0ES>. In fig-FORTH, this should be <BUILDS...D0ES>. 

NUMBER vs. NUMBER (page 285) 

Brodie's NUMBER only converts numbers to double length if the double word set 
is loaded. fig-FORTH always converts numbers to double length. 


PROVIDED THROUGH THE COURTESY OF VALPAR INTERNATIONAL CORPORATION; 3801 East 34th Street, 
Suite 105; Tucson, Arizona. Further distribution of this public domain document must in¬ 
clude this notice. 



>IN = IN, H = DP (page 247) 

The variable >IN and H in Brodie's FORTH are IN and DP respectively in 
fig-FORTH. 

VARIABLE vs. VARIABLE (page 209) 

The word VARIABLE, as Brodie describes it, accepts no value from the stack. 
fig-FORTH, on the other hand, does expect an initialization value from the stack. 


' vs. ' (page 215) 

These words are not synonymous. ' in Brodie is the same as ' 2- in fig-FORTH 
(or, more properly, ' CFA). 


PROVIDED THROUGH THE COURTESY OF VALPAR INTERNATIONAL CORPORATION; 3801 East 34th Street, 
Suite 105; Tucson, Arizona. Further distribution of this public domain document must in¬ 
clude this notice. 
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valFORTH 1.1 

T.M. 

Control Structures 


Stack inputs and outputs are shown; top of stack on right. 
This card follows usage of the Forth Interest Group 
(S.F. Bay Area); usage aligned with the Forth 78 
International Standard. 

For more info: Forth Interest Group 

P.0. Box 1105 
San Carlos, CA 94070. 


Operand Key: n,nl,. 

. 16-bit signed numbers 

d,dl,. 

. 32-bit signed numbers 

u 

16-bit unsigned number 

addr 

address 

b 

8-bit byte 

c 

7-bit ascii character value 

f 

boolean flag 

fp 

floating point number 

$ 

string 


Stack Manipulation 


DUP 

( n -- n n ) 

Duplicate top of stack. 

DROP 

( n .. ) 

Throw away top of stack. 

SWAP 

( nl n2 -- n2 nl ) 

Reverse top two stack items. 

OVER 

( nl n2 — nl n2 nl ) 

Make copy of second item on top. 

ROT 

( nl n2 n3 -- n2 n3 nl ) 

Rotate third item to top. 

<R0T 

( nl n2 n3 -- n3 nl n2 ) 

Rotate top item to third. 

-DUP 

( n — n ? ) 

Duplicate only if non-zero. 

>R 

( n — ) 

Move top item to "return stack" for temporary 
storage (use caution). 

R> 

( — n ) 

Retrieve item from return stack. 

R 

( — n ) 

Copy top of return stack onto stack. 

Number Bases 


DECIMAL 

( - ) 

Set decimal base. 

HEX 

( -- ) 

Set hexadecimal base. 

BASE 

( -- addr ) 

System variable containing number base. 

Arithmetic and Logical 


+ 

( nl n2 — sum ) 

Add. 

D+ 

( dl d2 -- sum ) 

Add double-precision numbers. 

- 

( nl n2 — diff ) 

Subtract (nl-n2). 

* 

( nl n2 — prod ) 

Multiply. 

/ 

( nl n2 -- quot ) 

Divide (nl/n2). 

MOD 

( nl n2 -- rem ) 

Modulo (i.e. remainder from division). 

/MOD 

( nl n2 — rem quot ) 

Divide, giving remainder and quotient. 

*/M0D 

( nl n2 n3 -- rem quot) 

Multiply, then divide (nl*n2/n3), with double¬ 
precision intermediate. 

*/ 

( nl n2 n3 -- quot ) 

Like */M0D, but give quotient only. 

MAX 

( nl n2 -- max ) 

Maximum. 

MIN 

( nl n2 -- min ) 

Minimum. 

ABS 

( n -- absolute ) 

Absolute value. 

DABS 

( d -- absolute ) 

Absolute value of double-precision number. 

MINUS 

( n — -n ) 

Change sign. 

DMINUS 

( d - -d ) 

Change sign of double-precision number. 

AND 

( nl n2 -- and ) 

Logical AND (bitwise). 

OR 

( nl n2 — or ) 

Logical OR (bitwise). 

XOR 

( nl n2 -- xor ) 

Logical exclusive OR (bitwise). 

NOT 

( n — f ) 

True if top number zero (i.e. reverses 
truth value). 

Comparison 


< 

( nl n2 — f ) 

True if nl less than n2. 

> 

( nl n2 -- f ) 

True if nl greater than n2. 

<= 

( nl n2 — 'f ) 

True if nl less than or equal to n2. 

>= 

( nl n2 — f ) 

True if nl greater than or equal to n2. 

= 

( nl n2 - f ) 

True if top two numbers are equal. 

<> 

( nl n2 — f ) 

True if nl does not equal n2. 

0< 

( n - f ) 

True if top number negative. 

0> 

( n - f ) 

True if top number positive. 

0= 

( n - f ) 

True if top number zero (i.e. reverses 

0# 

( n — f ) 

truth value. 

True if n does not equal zero. 

Memory 




( addr -- n ) 

Replace word address by contents. 

i 

( n addr -- ) 

Store second word at address on top. 

c@ 

( addr -- b ) 

Fetch one byte only. 

C! 

( b addr -- ) 

Store one byte only. 

•? 

( addr -- ) 

Print contents of address. 

c? 

( addr -- ) 

Print byte at address. 

u? 

( addr -- ) 

Print unsigned contents of address. 

+ ! 

( n addr -- ) 

Add second number on stack to contents of address 
on top. 

CM0VE 

( from to u -- ) 

Move u bytes in memory from head to head. 

<CM0VE 

( from to u — ) 

Move u bytes in memory from tail to tail. 

FILL 

( addr u b — ) 

Fill u bytes in memory with b, beginning at 
address. 

ERASE 

( addr u -- ) 

Fill u bytes in memory with zeroes, beginning at 
address. 

BLANKS 

( addr u -- ) 

Fill u bytes in memory with blanks, beginning at 


address. 


DO...LOOP 

do: ( end+1 start — 

I 

( — index ) 

r 

( — index ) 

j 

( — index ) 

LEAVE 

( - ) 

?EXIT 

( - ) 

DO... +L00P 

do: ( end+1 start — 
+loop: ( n — ) 

DO... /LOOP do: ( end+1 start -- 
/loop: ( u — ) 

IF...(true) 

if: ( f - ) 

...ENDIF 

IF...(true) 

...ELSE 

if: (f - ) 

...(false) 

...ENDIF 

BEGIN... 

until: ( f -- ) 

UNTIL 


BEGIN... 

while: (f -- ) 

WHILE 


...REPEAT 


Set up loop, given index range. 

Place current index value on stack. 

Used to retrieve index after a >R. 

Place index of outer D0-L00P on stack. 

Terminate loop at next LOOP, +L00P, or /LOOP. 
LEAVE if 7TERMINAL is true (i.e. pressed). 

Like DO...LOOP, but adds stack value (instead of 
always '1 *) to index. 

Like DO... +L00P, but adds unsigned value to 
index. 

If top of stack true (non-zero), execute. (Note: 
Forth 78 uses IF...THEN.) 

Same, but if false, execute ELSE clause. (Note: 
Forth 78 uses IF...ELSE...THEN.) 

Loop back to BEGIN until true at UNTIL. (Note: 
Forth 78 uses BEGIN...END.) 

Loop while true at WHILE;REPEAT loops uncondition¬ 
ally to BEGIN. (Note: Forth 78 uses BEGIN...IF 
...AGAIN.) 


Terminal 

Input - Output 


( n - ) 

!r 

( n fieldwidth -- ) 

D- 

( d - ) 

D.R 

( d fieldwidth -- ) 

CR 

( " ) 

SPACE 

( - ) 

SPACES 

( n - ) 

/ __ \ 

DUMP 

I ) 

( addr u -- ) 

TYPE 

( addr u -- ) 

COUNT 

( addr -- addr+1 u ) 

7TERMINAL 

( - f ) 

KEY 

( - c ) 

EMIT 

( c - ) 

EXPECT 

( addr n — ) 

WORD 

( c - ) 


Input - 

Output Formating 

NUMBER 

( addr -- d ) 

<ft 

( - ) 

it 

( d - d ) 

itS 

( d — 0 0 ) 

SIGN 

( n d -- d ) 

n*> 

( d -- addr u ) 

HOLD 

( c - ) 

Disk Handling 

LIST 

( screen — ) 

LOAD 

( screen -- ) 

BLOCK 

( block -- addr ) 

B/BUF 

( — n ) 

BLK 

( -- addr ) 

SCR 

( — addr ) 

UPDATE 

( - ) 

FLUSH 

( - ) 

EMPTY- 

BUFFERS 

( - ) 

Defining Words 

: XXX 

( - ) 

; 

( - ) 

VARIABLE 

xxx ( n — ) 

xxx: l -- addr ) 

CONSTANT 

xxx ( n - • ) 

xxx : ( — n ) 

CODE xxx 

( -- ) 

;C0DE 

( - ) 


<BUILDS... does: ( -- addr ) 

D0ES> 

LABEL xxx ( — addr ) 


Print number. 

Print number, right-justified in field. 

Print double-precision number 

Print double-precision number, right-justified in 
field. 

Do a carriage return. 

Type one space. 

Type n spaces. 

Print message (terminated by "). 

Dump u words starting at address. 

Type string of u characters starting at address. 
Change length-byte string to TYPE form. 

True if terminal break request present. 

Read key, put ascii value on stack. 

Type ascii value from stack. 

Read n characters (or until carriage return) from 
input to address. 

Read one word from input stream, using given 
character (usually blank) as delimiter. 


Convert string at address to double-precision number. 
Start output string. 

Convert next digit of double-precision number and 
add character to output string. 

Convert all significant digits of double-precision 
number to output string. 

Insert sign of n into output string. 

Terminate output string (ready for TYPE). 

Insert ascii character into output string. 


List a disk screen. 

Load disk screen (compile or execute). 

Read disk block to memory address. 

System constant giving disk block size in bytes. 
System variable containing current block number. 
System variable containing current screen number. 
Mark last buffer accessed as updated. 

Write all updated buffers to disk. 

Erase all buffers. 


Begin colon definition of xxx. 

End colon definition. 

Create a variable named xxx with initial value n; 
returns address when executed. 

Create a constant named xxx with value n; returns 
value when executed. 

Begin definition of assembly-language primitive 
operative named xxx. 

Used to create a new defining word, with execution¬ 
time "code routine" for this data type in assembly. 
Used to create a new defining word, with execution¬ 
time routine for this data type in higher-level Forth. 
Creates a header xxx which when executed returns its 
PFA. 
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HANDY REFERENCE CARD 

va/FORTH 1.1 va/FORTH„ Memory Map 


Vocabularies 



CONTEXT ( 

-- addr ) 

Returns address of pointer to context vocabulary 



' (searched first). 


CURRENT ( 

— addr ) 

Returns address of pointer to current vocabulary 
(where new definitions are put). 


FORTH ( 

- ) 

Main Forth vocabulary (execution of FORTH sets 

CONTEXT vocabulary). 


EDITOR 1 

- ) 

Editor vocabulary; sets CONTEXT. 


ASSEMBLER 1 

- ) 

Assembler vocabulary; sets CONTEXT. 


DEFINITIONS I 

: - ) 

Sets CURRENT vocabulary to CONTEXT. 


VOCABULARY 1 

[ - > 

Create new vocabulary named xxx. 


XXX 

VLIST l 

: - ) 

Print names of all words in CONTEXT vocabulary. 

DP 

Miscellaneous and System 



( 

FORGET xxx 

ABORT 

'xxx 

( - ) 

( -- ) 

( - ) 

( — addr ) 

Begin comment, terminated by right paren on same 
line; space after ( . 

Forget all definitions back to and including xxx. 

Error termination of operation. 

Find the address of xxx in the dictionary; if used 

LIMIT 

FIRST 

in definition, compile address. 

HERE 

( -- addr ) 

Returns address of next unused byte in the 


PAD 

( — addr ) 

dictionary. 

Returns address of scratch area (usually 128 bytes 

$0700 

IN 

( — addr ) 

beyond HERE). 

System variable containing offset into input buffer. 

$0600 



Used, e.g., by WORD. 

$05FF 

SP@ 

( -- addr ) 

Returns address of top stack item. 

ALLOT 

( n — ) 

Leave a gap of n bytes in the dictionary. 


• 

( n - ) . 

Compile a number into the dictionary. 

$057E 


STANDARD DISPLAY 
MEMORY AREA 



PAD 

$0080 BYTES 


USE 

PREV 

0 +ORIGIN 


o 


USER AREA 


$0480 

$01FF 

RP 

$0100 

$00FF 

$0004 


RETURN STACK . 

..-TERMINAL BUFFER 


-UP 

-R0 

IN 

-TIB 


ATARI FLOATING POINT 


Z PAGE 


UP N IP W 


SO 

SP 


STACK $00BC-$0080 


SP ts X REGISTER 
RP IS STACK POINTER 
OF CPU 



Ai*/t is a tiatomw* of Atari Inc , a division of Wamof Communications 


o 
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Graphics and Color 

SETCOLOR ( nl n2 n3 -- ) Color register nl (0...3 and 4 for background) 

is set to hue n2 (0 to 15) and luminance n3 
(0-14, even). 

SE. ( nl n2 n3 — ) Alias for SETCOLOR. 

GR. ( n — ) Identical to GR. in BASIC. Adding 16 will 

suppress split display. Adding 32 will suppress 
display preclear. In addition, this GR. will 
not disturb player/missiles. 

POS. ( x y -- ) Same as BASIC POSITION or POS. Positions the 

invisible cursor if in a split display mode, 
and the text cursor if in 0 GR. . 

POSIT ( x y -- ) Positions and updates the cursor, similar to 

PLOT, but without changing display data. 

PLOT ( x y -- ) Same as BASIC PLOT. PLOTs point of color in 

register specified by last COLOR command, at 
point x y. 

DRAWTO ( x y -- ) Same as BASIC DRAWTO. Draws line from last 

PLOT 1 ted, DRAWTO'ed or POSIT'ed point to x y, 
using color in register specified by last COLOR 
command. 

DR. ( x y — ) Alias for DRAWTO. 

FIL ( b -- ) Fills area between last PLOT'ted, DRAWTO'ed or 

POSIT'ed point to last position set by POS., 
using the color in register b. 

G" ( -- ) Used in the form G“ ccccc". Sends text cccc to 

text area in non-0 Graphics mode, starting at 
current cursor position, in color of register 
specified by last COLOR command prior to cccc 
being output. 

GTYPE ( addr count -- ) Starting at addr, output count characters to 

text area in non-0 Graphics mode, starting at 
current cursor position, in color of register 
specified by last COLOR command. 

LOC. ( x y -- b ) Positions the cursor at x y and fetches the 

data from display at that position. Like 
BASIC LOCATE and LOC. . 

(G") ( — ) . Run-time code compiled in by G". 

P0S@ ( -- x y ) Leaves the x and y coordinates of the cursor 

on the stack. 

CPUT ( b -- ) Outputs the data b to the current cursor 

position. 

CGET ( -- b ) Fetches the data b from the current cursor 

position. 

>SCD ( cl -- c2 ) Converts cl from ATASCII to its display screen 

code, c2. Example: ASCII A >SCD 88 @ C! 
will put an "A" into the upper left corner of 
the display. 

SCD> ( cl -- c2 ) Converts cl from display screen code to ATASCII 

_ c2. See >SCD. 

>BSCD ( addrl addr2 count — ) Moves count bytes from addrl to addr2, 

translating from ATASCII to display screen 
code on the way. 

BSCD> ( addrl addr2 count — ) Moves count bytes from addrl to addr2, 

translating from display screen code to 
ATASCII on the way. 

COLOR ( b -- ) Saves the value b in the variable CLRBYT. 

CLRBYT ( -- addr ) Variable that holds data from last COLOR 

command. 


GREY 

0 

PINK 

-- 4 

BLUE 

8 

GREEN 

- 12 

GOLD 

1 

LVNDR 

- 5 

LTBLUE — 

9 

YLWGRN 

- 13 

ORNG 

2 

BLPRPL 

— 6 

TURQ 

10 

ORNGRN 

- 14 

RDORNG — 

3 

PRPLBL 

-- 7 

GRNBL — 

11 

LTORNG 

- 15 


(CONSTANTS) 


SOUND ( chan freq dist vol — ) Sets up the sound channel "chan" as indicated. 

Channel: 0-3 

Frequence: 0-255, 0 is highest pitch. 

Distortion: 0-14, evens only. 

Volume: 0-15. 

Suggested mnemonic: CatFish Don't Vote 
SO. ( chan freq dist vol -- ) Alias of SOUND. 

FILTER! ( n -- ) Stores n in the audio control register and into 

the valFORTH shadow register, AUDCTL. Use 
AUDCTL when doing bit manipulation, then do 
FILTER!. 

AUDCTL ( -- addr ) A variable containing the last value sent to the 

audio control register by FILTER!. 

XSND ( n -- ) Silences channel n. 

XSND4 ( -- ) Silences all channels. 

Text Output and Disk Preparation 

S: ( flag — ) If flag is true, enables handler that sends 

text to text screen. If false, disables the 
handler. (See PFLAG in main glossary.) 

( flag -- ) If flag is true, enables handler that sends 

text to printer. If false, disables the 
handler. (See PFLAG in main glossary) 

BEEP ( -- ) Makes a raucous noise from the keyboard. 

ASCII ( c, — n (executing) ) Converts next character in input stream to 

( c, — (compiling) ) ATASCII code. If executing, leaves on stack. 

If compiling, compiles as literal. 

EJECT ( -- ) Causes a form feed on smart printers if the 

printer handler has been enabled by ON P:. 

May need adjustment for dumb or nonstandard 
printers. 

LISTS ( start count — ) From start, lists count screens. May be aborted 

by CONSOLE button at the end of a screen. 

PLIST ( scr — ) Lists screen scr to the printer, then restores 

former printer handler status. 

PLISTS ( start cnt — ) From start, lists cnt screens to printer three 

to a page, then restores former printer handler 
status. May be aborted by CONSOLE button at 
the end of a screen. 

FORMAT ( -- ) With prompts, will format a disk in drive of 

your choice. 


Debugging Utilities 


DECOMP 

xxx 


Does a decompilation of the word xxx if it can 
be found in the active vocabularies. 

CDUMP 

( addr n -- 

) 

A character dump from addr for at least n 
characters. (Will always do a multiple of 16.) 

#DUMP 

( addr n -- 

) 

A numerical dump in the current base for at 
least n characters. (Will always do a multiple 
of 8.) 

(FREE) 

( — n ) 


Leaves number of bytes between bottom of display 
list and PAD. 

FREE 

( -- ) 


Does (FREE) and then prints the stack and 
"bytes". 

H. 

( n — ) 


Prints n in HEX, leaves BASE unchanged. 

STACK 

( flag — ) 


If flag is true, turns on visible stack. 

If flag is false, turns off visible stack. 

.S 

t ... - ... 

) 

Does a signed, nondestructive stack printout, 

TOS at right. Also sets visible stack to do 
signed printout. 

U.S 

i ... - ... 

) 

Does unsigned, nondestructive stack printout, 

TOS at right. Also sets visible stack to do 
unsigned printout. 

B? 

< - > 


Prints the current base, in decimal. Leaves 

BASE undisturbed. 

CFALIT 

xxx ( -- cfa (executing)) 

Gets the cfa (code field address) of xxx. If 

xxx ( — 

Floating Point 

(compiling)) 

executing, leaves it on the stack; if compiling, 
compiles it as a literal. 

FCONSTANT 

xxx ( fp — ^ 

) 

The character string is assigned the constant 


xxx ( — fp ) 

value fp. When xxx is executed, fp will be 
put on the stack. 

FVARIABLE 

xxx (fp -- ) 


The character string xxx is assigned the 


xxx: ( addr - 

- > 

initial value fp. When xxx is executed, the 
addr (two bytes) of the value of xxx will be 
put on the stack. 

FDUP 

( fpl — fpl 

fpi i 

Copies the fp number at top-of-stack. 

FDROP 

( fp - ) 


Discards the fp number at top-of-stack.) 

FOVER 

( fp2 fpl — 

fp2 fpi fp2 ; 

i Copies the fp number at 2nd-on-stack to 
top-of-stack. 

FLOATING 

xxx ( -- fp ; 

) 

Attempts to convert the following string, xxx, 
to a fp number. 

FP 

xxx ( -- fp ' 

i 

Alias for FLOATING. 

FO 

( addr -- fp 

) 

Fetches the fp number whose address is at 
top-of-stack. 

F! 

( fp addr -- 

) 

Stores fp into addr. Remember that the 
operation will take six bytes in memory. 

F. 

< fp -- i 


Type out the fp number at top-of-stack. 

Ignores the current value in BASE and uses 
base 10. 

F? 

( addr — ) 


Fetches a fp number from addr and types it out. 

F+ 

( fp2 fpl - 

fp3 ) 

Replaces the two top-of-stack fp items, fp2 and 
fpl, with their fp sum, fp3. 

F- 

( fp2 fpl — 

fp3 ) 

Replaces the two top-of-stack fp items fp2 and 
fpl, with their difference, fp3=fp2-fpl. 

F* 

( fp2 fpl - 

fp3 ) 

Replaces the two top-of-stack fp items fp2 and 
fpl, with their product, fp3. 

F/ 

( fp2 fpl - 

fp3 1 

Replaces the two top-of-stack fp items fp2 and 
fpl, with their quotient, fp3=fp2/fpl. 

FLOAT 

( n -- fp ) 


Replaces number at top-of-stack with its fp 
equivalent. 

FIX 

( fp (non-nec 

1. less 

Replaces fp number at top-of-stack, constrained 


than 32767.5) — n ) 

as indicated, with its integer equivalent. 

LOG 

(fpl - fp2 

) 

Replaces fpl with its base e logarithm, fp2. 

Not defined for fpl negative. 

L0G10 

( fpl - fp2 

) 

Replaces fpl with its base 10 decimal logarithm, 
fp2. Not defined for fpl negative. 

EXP 

( fpl - fp2 

) 

Replaces fpl with fp2, which equals e to the 
power fpl. 

EXP10 

( fpl - fp2 

) 

Replaces fpl with fp2, which equals 10 to the 
power fpl. 

FO* 

1 fp -- flag 

) 

If fp is equal to floating-point 0, a true 
flag is left. Otherwise, a false flag is left. 

F= 

( fp2 fpl - 

flag ) 

If fp2 is equal to fpl, a true flag is left. 
Otherwise, a false flag is left. 

F> 

( fp2 fpl - 

flag ) 

If fp2 is greater than fpl, a true flag is 
left. Otherwise, a false flag is left. 

F< 

( fp2 fpl - 

flag ) 

If fp2 is less than fpl, a true flag is left. 
Otherwise, a false flag is left. 

FLITERAL ( fp - ) 

Operating System 


If compiling, then compile the fp stack value 
as a fp 1iteral. 

OPEN 

( addr nO nl 

n2 — n3 ) 

This word opens the device whose name is at 
addr. The device is opened on channel nO with 
AUX1 and AUX2 as nl and n2 respectively. The 
device status byte is returned as n3. 

CLOSE 

( n - ) 


Closes channel n. 

PUT 

( bl n — b2 

) 

Outputs byte bl on channel n, returns status 
byte b2. 

GET 

( n — bl b2 

) 

Gets byte bl from channel n, returns status 
byte b2. 

GETREC 

( addr nl n2 

-- n3 ) 

Inputs record from channel n2 up to length nl. 
Returns status byte n3. 

PUTREC 

( addr nl n2 

-- n3 ) 

Outputs nl characters starting at addr through 
channel n2. Returns status byte n3. 

STATUS 

( n — b ) 


Returns status byte b from channel n. 

DEVSTAT 

( n — bl b2 

b3 ) * 

From channel nl gets device status bytes bl and 
b2, and normal status byte b3. 

SPECIAL 

( bl b2 b3 b4 

b5 b6 

Implements the Operating System "Special" 


b7 b8 — b9 

) 

command. AUX1 through AUX6 are bl through b6 
respectively, command byte is b7, channel number 
is b8. Returns status byte b9. 

RS232 

( -- > 


Loads the Atari 850 drivers into the dictionary 


(approx 1.8K). 


Software and Documentation 
©Copyright 1982 
Valpar International 


HANDY REFERENCE CARD 

vaiFORTH 1.1 

T.M 


vaiFORTH 6S02 Assembler 


ASSEMBLER ( — ) 

CODE xxx { — ) 

C; ( — ) 

END-CODE ( — ) 
SUBROUTINE xxx ( — ) 

'.CODE ( — ) 

Control Structures 


Calls up the assembler vocabulary for subsequent 
assembly language programming. 

Enters the new word "xxx" into the dictionary 
as machine language word and calls up the 
assembler vocabulary for subsequent assembly 
language programming. 

Terminates an assembly language definition by 
performing a security check and setting the 
CONTEXT vocabulary to the same as the CURRENT 
vocabulary. , 

A commonly used synonym for the word C; above. 
The word C; is reconmended over END-CODE. 

Enters the new word "xxx" into the dictionary 
as machine language subroutine and calls up 
the assembler vocabulary for subsequent assembly 
language programming. 

When the assembler is loaded, puts the system 
into the assembler vocabulary for subsequent 
assembly language programming. See main 
glossary for further explanation. 


IF, 


ELSE, 


( flag — addr 2 ) 


( addr 2 — addr 3 ) 


ENDIF, 

( addr 2/3 — 

BEGIN, 

( — addr 1 ) 

UNTIL, 

( addr 1 flag - 

WHILE, 

( addr 1 flag 

REPEAT, 

( addr 4 — ) 

AGAIN, 

( addr 1 — ) 

Parameter Passing 

NEXT 

( — addr ) 

PUSH 

( — addr ) 

PUSHOA 

( --- addr ) 

PUT 

( — addr ) 

PUTOA 

( — addr ) 

BINARY 

( — addr ) 

POP and 
POPTWO 

( — addr ) 

SETUP 

( — addr ) 

N 

( — addr ) 

Opcodes 

( various — 


Begins a machine language control structure 
based on the 6502 status flag on top of the 
stack. Leaves an address and a security check 
value for the ELSE, or ENDIF, clauses below, 
"flag" can be EQ , NE , CC , CS , VC , VS , 

MI , or PL . Command forms: 

... flag..IF,..if-true..ENDIF,...all... 

... flag..IF,..if-true.. 

ELSE,..If-false..ENDIF,..all... 

Used in an IF, clause to allow for execution 
of code only if IF, clause is false. If the IF, 
clause is true, this code is bypassed. 

) Used to terminate an IF, control structure 

clause. Additionally, ENDIF, resolves all 
forward references. See IF, above for command 
form. 

Begins machine language control structures of 
the following forms: 

...BEGIN,...AGAIN,... 

...BEGIN,...flag..UNTIL,... 

...BEGIN,...flag..WHILE,..while-true..REPEAT,... 
where "flag" is one of the 6502 statuses: EQ , 

NE , CC , CS , VC , VS , MI , and PL . 

— ) Used to terminate a post-testing BEGIN, clause 

thus allowing for conditional looping of a 
program segment while "flag" is false. 

— addr 4 ) Used to begin a pre-testing BEGIN, clause thus 

allowing for conditional looping of a program 
segment while "flag" is true. 

Used to terminate a pre-testing BEGIN,..WHILE, 
clause. Additionally, REPEAT, resolves all 
forward addresses of the current WHILE, clause. 
Used to terminate an unconditional BEGIN, 
clause. Execution cannot exit this loop unless 
a JMP, instruction is used. 

(These routines must be jumped to.) 

Transfers control to the next FORTH word to be 
executed. The parameter stack is left unchanged. 
Pushes a 16 bit value to the parameter stack 
whose low byte is found on the 6502 return 
stack and whose high byte is found in the 
accumulator. 

Pushes a 16 bit value to the parameter stack 
whose low byte is found in the accumulator and 
whose high byte is zero. 

Replaces the value currently on top of the 
parameter stack with the 16 bit value whose 
low byte is found on the 6502 stack and whose 
high byte is in the accumulator. 

Replaces the value currently on top of the 
parameter stack with the 16 bit t value whose 
low byte is in the accumulator and whose high 
byte is set to zero. 

Drops the top value of the parameter stack 
and then performs a PUT operation described 
above. 

POP drops one value from the parameter stack. 
POPTWO drops two values from the parameter 
stack. 

Moves one to four values to the N scratch area 
in the zero page and drops all values moved 
from the parameter stack. 

Points to a nine-byte scratch area inthe zero 
page beginn 

various ) 


Aliases 


NXT, 

PSH, 

PUT, 

PSHA, 

PUTA, 

POP, 


NEXT JMP, 
PUSH JMP, 
PUT JMP, 
PUSHOA JMP, 
PUTOA JMP, 
POP JMP, 


page 

beginning at N-l 

and going to 

N+7. 

CLI, 

ADC, 

AND, 

ASL, 

BIT, 

BRK, 

CLC, 

CLD, 

CLV, 

CMP, 

CPX, 

CPY, 

DEC, 

DEX, 

DEY, 

EOR. 

INC, 

INX, 

INY, 

JSR, 

JMP, 

LDA, 

LDX, 

LDY. 

LSR, 

NOP, 

ORA, 

PHA. 

PHP, 

PLA, 

PLP, 

ROL. 

ROR, 

RTI, 

RTS, 

SBC, 

SEC, 

SED, 

SEI, 

STA, 

STX, 

TAX, 

TAY, 

TSX, 

TXA, 

TXS, 

TYA, 


POP2, 

_ 

POPTWC 

1 JMP, 





XL, 

= 

XSAVE 

LDX, 





XS, 

= 

XSAVE 

STX, 





THEN, 

= 

ENDIF, 






END, 

= 

UNTIL, 










V. ^ 
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SOFTWARE SYSTEM 

EDJTQfi 1.1 COMMAND SUMMARY 

Below Is a quick reference list of all the commands which the video editor 
recognizes. 


Entering the Edit Mode (executed outside of the edit mode) 


V ( 

L ( 

WHERE ( 

LOCATE cccc ( 

LOCATOR ( 

#BUFS ( 


scr# —- ) 
— ) 

— ) 

... ) 

ON/OFF --- ) 
#lines — ) 


* Enter the edit mode and view the specified screen. 

* Re-view the current screen. 

* Enter the edit mode and position the cursor over 
the word that caused a compilation error. 

Enter the edit mode and position the cursor over 
the word "cccc" where it is defined. 

When ON, allows all words compiled until the next 
OFF to be locatable using the LOCATE command above. 
Sets the length (in lines) of the storage buffer. 
The default is five. 


Cursor Movement (issued within the edit mode) 


Ctrl 

t 

Ctrl 


Ctrl 

<- 

Ctrl 

-» 

RETURN 


TAB 



* Move cursor up one line, wrapping to the bottom line 
if moved off the top. 

* Move cursor down one line, wrapping to the top line 
if moved off the bottom. 

* Move cursor left one character, wrapping to the 
right edge if moved off the left. 

* Move cursor right one character, wrapping to the 
left edge if moved off the right. 

Position the cursor at the beginning of the next 
line. 

Advance to next tabular column. 


Editing Commands (issued within the edit mode) 


Ctrl 

INS 

Ctrl 

DEL 

shift 

INS 

shift 

Ctrl 

DEL 

I 

BACKS 


Ctrl 

H 


Insert one blank at cursor location, losing the 
last character on the line. 

Delete character under cursor, closing the line. 

* Insert blank line above current line, losing the 
last line on the screen. 

* Delete current cursor line, closing the screen. 
Toggle insert-mode/replace-mode. 

(see full description of Ctrl-I). 

* Delete last character tvped, if on the same line 
as the cursor. 

E r ase to end of Hne (Mack). 




Buffer Management (issued within the edit mode) 


Ctrl 

T 

Delete current cursor line sending 
it to the edit buffer for later use. 

Ctrl 

F 

Take the current buffer line and insert, it 
above the current cursor line. 

Ctrl 

K 

Copy current cursor line sendinq it to the 
edit buffer for later use. 

Ctrl 

U 

Take the current* buffer line and copy it 
to the current cursor line. 

Ctrl 

R 

Roll the buffer making the topmost buffer 
line current. 

Ctrl 

B 

Roll the buffer backwards making the fourth 
* buffer line on the screen current. 

Ctrl 

C 

Clear the current* buffer line and performs 
a ctrl-B. 


*Note: The current buffer line is bottommost on the video display. 


Changing Screens (issued within the edit mode) 


Ctrl P 

Ctrl N 

Ctrl S 

Ctrl Q 


Display the previous screen saving all 
changes made to the current screen. 

DisDlay the next screen saving all changes 
made to the current screen. 

* Save the changes made to the current screen 
and end the edi* session. 

* Quit the edit session forgetting all changes 
made to the current screen. 


Special Keys (issued within the edit mode) 


ESC * Do not interpret the next key typed as any 




of the commands ::bo 

ve. Sei 

id it directly to 



the s 

creen instead. 



Ctrl 

A 

Put t. 

he arrow ” —> “ 

("next 

screen") in the 



lower 

-right-hand co 

rner of 

the scree" unless 



it is 

already there 

. in wh’ 

ich case remove it. 

Ctrl 

J 

Split 

the current 1 

ine into two line; at the 



where 

the cursor is 



Ctrl 

0 

Ccrre 

cts any major 

editing 

blunders. 


Screen Management (executed outside of the edit mode) 


r 

. ^ 


FLUSH 

( -- ) 


* 

Save any updated FORTH screens to disk. 

EMPTY- 
BUFFERS 

( - ) 


* 

Forget any changes made to any screens not yet 
FLUSHed to disk. 

COPY 

( from 

to — ) 

* 

Copies screen #from to screen =to. 

CLEAR 

( scr# 

- ) 

* 

Blank fills specified screen. 

CLEARS 

( scr# 

#screens -- ) 


Blank fills the specified number of screens start¬ 
ing with screen scr#. 

SMOVE 

( from 

to #screens -- 

) 

Duplicate the specified number of screens Starting 
with screen number "from". 


* EDITOR 1.0 COMMAND 
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